<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{uFldHazardMgr: On-Board Management of a Hazard Sensor}
\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.UFldHazardMgr}
\wikidoc{bugz=uFldHazardMgr}
\wikidoc{auth=mikerb@mit.edu}

%====================================================================
\section{Overview}
%====================================================================
\label{sec_ufld_hmanager}
\index{uFldHazardMgr}

The \app{uFldHazardMgr} application is {\em straw man} module for
interacting with an on-board hazard sensor. It does two basic things
as implied in Figure \ref{fig_uhma_overview}:

\begin{packed_enumerate}[3]
\item {\em Interacts with the sensor}: It decides a sensor
  configuration setting and sends this to the hazard sensor. It may
  change settings during the course of the mission to its
  advantage. It interacts with the sensor by sending sensor requests,
  and receiving sensor reports. It has some knowledge of the sensor
  properties and configuration options.
\item {\em Generates a hazardset report}: It builds an internal belief
  state regarding the identification and location of hazards, and
  reports this belief state upon request.
\end{packed_enumerate}

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/uhma_overview.png}
  \caption{{\bf The uFldHazardMgr}: interacts with the on-board sensor
    and processes sensor information and generates a report, upon
    request, regarding the identification and location of hazards. The
    arrows indicate the key MOOS variables used for interacting with
    the sensor and generating reports.}
\label{fig_uhma_overview}
\end{figure}
\vspace{0.1in}

\noindent
There are many ways to interpret sensor data and ultimately decide upon
a hazardset report. For this reason we regard \app{uFldHazardMgr} as a 
{\em straw man} module. It implements the key syntactic steps to minimally
configure and interact with the sensor and produce a syntactically correct
hazardset report. The intention is that users may wish to use this as a 
starting point. 

\pskip

A further aspect one may wish to include in this module would be a
form of reasoning about the vehicle's path through the hazard
field. This module, and accompanying example mission, was written with
the vehicle simply performing a lawnmower exhaustive search through
the field. This module could be used in conjunction with the helm to 
decided follow-up search patterns or collaborative strategies with other
vehicles. Again, this is not part of \app{uFldHazardMgr} since the
objective of this module is to provide a syntactically valid starting
point for managing sensor information.

%====================================================================
\section{Using uFldHazardMgr}
%====================================================================

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

The typical module topology is shown in Figure \ref{fig_uhma_topology}
below. The \app{uFldHazardMgr} is situated in the vehicle MOOS
community. It interacts with the \app{uFldHazardSensor} situated in
the shoreside MOOS community. The vehicle communicates with the
shoreside community using \app{pShare}. The shoreside knows the
location of all vehicles from node reports received from each vehicle
running \app{pNodeReporter}. The \app{uFldHazardMgr} first initializes
the sensor by sending a configuration request via
\mvar{UHZ\_CONFIG\_REQUEST}. The hazard sensor acknowledges the
configuration with a \mvar{UHZ\_CONFIG\_ACK} message. Thereafter
the hazard manager may interact with the sensor by sending sensor 
requests with \mvar{UHZ\_SENSOR\_REQUEST} and periodically receiving
reports of detections with \mvar{UHZ\_DETECTION\_REPORT}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/uhma_topology.png}
  \caption{{\bf Typical uFldHazardMgr Topology:} The simulator runs in
    a shoreside computer MOOS community and is configured with a
    hazard field containing both hazards and benign objects.  Vehicles
    accessing the simulator send a steady stream of messages
    (\mvvar{UHZ\_SENSOR\_REQUEST}) and node reports to the shoreside
    community. The simulator continuously checks the connected
    vehicle's position against objects in the hazard field, and the
    sensor settings. When/if an object comes into sensor range, the
    simulator rolls the dice and if a detection is made, will send a
    \mvvar{UHZ\_DETECTION\_REPORT} message to the vehicle. The vehicle
    may periodically re-configure its sensor setting by posting to
    \mvvar{UHZ\_CONFIG\_REQUEST}. If the configuration request is
    acceptable, the simulator will respond with a message to
    \mvvar{UHZ\_CONFIG\_ACK} bridged back out to the vehicle.}
\label{fig_uhma_topology}
\end{figure}

\vspace{0.1in}
\noindent
The hazard manager maintains a history of reported detections and
listens for requests, via the variable \mvar{HAZARDSET\_REQUEST}, to
generate a {\em hazardset report}. It will respond to the request by
posting a hazardset report in the variable \mvar{HAZARDSET\_REPORT}.


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

Using \app{uFldHazardMgr} requires certain information flowing between
the shoreside and vehicles communities as shown in Figure
\ref{fig_uhma_topology}. The bridging is done by \app{pShare}, but the
\app{pShare} configuration is handled dynamically using the
\app{uFldNodeBroker} and \app{uFldShoreBroker} applications, we
discuss here the necessary configuration entries for these two
applications.  From the vehicle to the shoreside, five variables need
to be bridged. The below five 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=UHZ_SENSOR_CONFIG
  bridge =  src=UHZ_SENSOR_REQUEST
  bridge =  src=HAZARDSET_REPORT
\end{verbatim}
\postverb

\noindent
The first two lines above would likely already be present due to their
use in other applications. The latter three variables are generated by
\app{uFldHazardMgr} with the intended recipient being
\app{uFldHazardSensor} on the shoreside. The latter variable,
\mvar{HAZARDSET\_REPORT}, constitutes the hazardset report generated by
\app{uFldHazardMgr}.  The above five lines may also be found in the
vehicle configuration for the Jake Kasper example mission discussed in
Section \ref{sec_uhma_jake}.

\pskip

The below four lines should appear in the \app{uFldShoreBroker} configuration
block in the shoreside MOOS community. See \app{uFldShoreBroker} documentation
for a discussion on the syntax.

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

  bridge =  src=APPCAST_REQ 
  bridge =  src=UHZ_CONFIG_ACK_$V,       alias=UHZ_CONFIG_ACK
  bridge =  src=UHZ_DETECTION_REPORT_$V, alias=UHZ_DETECTION_REPORT
  bridge =  src=HAZARDSET_REQUEST_$V,    alias=HAZARDSET_REQUEST
\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
allows sensor configuration acknowledgments to be sent to the vehicle
(Section \ref{sec_uhma_swath}). The third line allows detection
reports to be sent to the vehicle (Section
\ref{sec_uhma_detect_reports}).  The last line allows an app running
on the shoreside to bridge requests to the vehicle for a hazardset
report.  The above four lines may also be found in the shoreside
configuration for the Jake Kasper example mission discussed in Section
\ref{sec_uhma_jake}.

%====================================================================
\subsection{Configuration Parameters of uFldHazardMgr}
\index{uFldHazardMgr!Configuration Parameters}
\index{Configuration Parameters!uFldHazardMgr}

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{uFldHazardMgr}}
\label{lst_uhma_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.69\textwidth}} 

  \pvar{swath\_width}: &amp; The desired sensor swath width. Legal values:
  the set of widths available to the sensor. The default is 25. If the
  requested swath width setting is not available, the result will be
  the closest setting available.  \ref{sec_uhma_swath}. \\

  \pvar{pd}: &amp; The chosen probability of detection on the ROC curve
  determined by the sensor swath width. Legal values: the range
  $[0,1]$.  The default is $0.9$.  Section \ref{sec_uhma_pd}. \\

\end{longtable}
\end{listing}

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

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

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

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

\vspace{0.25in}
\begin{listing}{Example configuration of the uFldHazardMgr application}
\label{lst_uhma_econfig}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  uFldHazardMgr Example MOOS Configuration                   
  3  =============================================================== 
  4                                                                  
  5  ProcessConfig = uFldHazardMgr                                   
  6  {                                                               
  7    AppTick   = 4                                                 
  8    CommsTick = 4                                                 
  9                                                                  
 10    swath_width = 25       // the default                                       
 11    sensor_pd   = 0.9      // thd default                         
 12  }                        
\end{verbatim}
\end{listing}
\normalsize
 
%====================================================================
\subsection{Configuring the Swath Width}
\label{sec_uhma_swath}

Part of the initial responsibility of the hazard manager is to select
the sensor settings. There are two primary settings, the
\pvar{swath\_width} and \pvar{sensor\_pd} setting. The swath width
refers to the width, stetching outward away from the sides of the
vehicle. The selected width refers to the length on one side, so the
{\em total} swath width is twice the \pvar{swath\_width} setting.

\pskip

Physical sensors are usually built with no more than a few swath width
settings. These choices are known ahead of time. It is reasonable
therefore to expect the configuration of \app{uFldHazardMgr} to
reflect one of those choices. In our case, the available choices are
the prevailing values configured of \app{uFldHazardSensor}. In the
Jake example mission, the hazard sensor is configured to support
sensor swath widths of $10$, $25$, and $50$ meters. A sensor
configuration request is made to the sensor by the hazard manager
making a post to the \mvar{UHZ\_CONFIG\_REQUEST} variable similar to:

\prevgreen
\begin{verbatim}
  UHZ_CONFIG_REQUEST = "vname=archie,width=25,pd=0.85"
\end{verbatim}
\postverb

\noindent
The request width sent by the hazard manager is set in the \app{uFldHazardMgr}
configuration block: (See also Listing \ref{lst_uhma_econfig}.)

\prevblue
\begin{verbatim}
  swath_width = 25
\end{verbatim}
\postverb

\noindent
The hazard sensor, once it has received the configuration request, posts a 
configuration acknowledgement, which is bridged back to the vehicle:

\prevgreen
\begin{verbatim}
  UHZ_CONFIG_ACK = "vname=archie,width=25,pd=0.85,pfa=0.53,pclass=0.91"
\end{verbatim}
\postverb[0in]

%====================================================================
\subsection{Configuring the Probability of Detection Setting}
\label{sec_uhma_pd}

The second component of setting the sensor is choosing a probability
of detection setting. The $\pd$ is a number in the range of $[0,1]$
and is accompanied by a corresponding probability of false alarm,
$\pfa$.  The relationship between $\pd$ and $\pfa$ is determined
by the ROC curve related to the chosen sensor swath. This relationship
is described in the documentation for \app{uFldHazardSensor}.

%in Section \ref{sec_ufhz_roc_config}, in Figure \ref{fig_ufhz_roc_all}.

%====================================================================
\section{Under the Hood - Interacting with the Hazard Sensor}
\label{sec_uhma_detect_reports}

After the initial configuration, the hazard manager interacts with the
hazard sensor by posting sensor requests, and periodically receiving 
detection reports. These may look something like:

\mivar{UHZ\_SENSOR\_REQUEST}
\mivar{UHZ\_DETECTION\_REPORT}
\prevgreen
\begin{verbatim}
  UHZ_SENSOR_REQUEST   = "vname=archie"
  UHZ_DETECTION_REPORT = "x=-150.3,y=-117.5,label=12"
\end{verbatim}
\postverb

\noindent
The request contains only the vehicle name. The hazard sensor is
already receiving reports of the vehicle position, and has knowledge
of the hazard field. So the sensor only needs to know that the vehicle
indeed wishes to be sent detection reports.  

\pskip
Detection reports are only sent by the sensor when a detection is
made. The simulated sensor does not send sensor images or data, but
simulated {\em results} of sensor data, in the form of a declared
detection. The simulated hazard sensor makes life a bit artificially
easier by posting a detection {\em label}. This allows the user to 
make multiple passes over the same area and be sure that one hazard
is not showing up as several hazards each with a slightly different
location.

%====================================================================
\section{Under the Hood - Processing Data and Generating Reports}
\label{sec_uhma_hset_reports}

Hazardset reports are generated on-demand. First a request is received, 
immediately followed by the posting of a report. They may look similar
to:

\prevgreen
\begin{verbatim}
  HAZARDSET_REQUEST = "true"
  HAZARDSET_REPORT  = "source=archie#x=-151,y=-217.3,label=01#x=-178.8,y=-234,label=15#
                      x=-59.8,y=-294.1,label=13#x=-150.3,y=-117.5,label=12#
                      x=-14.2,y=-293.60001,label=08#x=-65.8,y=-125.2,label=10" 
\end{verbatim}
\postverb

\noindent
The content of the \mvar{HAZARDSET\_REQUEST} does not matter to 
\app{uFldHazardMgr}. It will interpret this mail as a request to generate
a report regardless of the request content.  

\pskip

The \mvar{HAZARDSET\_REPORT} content consists of a series of packets
separated by the \var{'\#'} character. The first packet names the
source of the report and the remaining packets each declare the
presence of a hazardous object and its location and label. The format
of the report is embodied in the class \var{XYHazardSet} in
\var{lib\_ufld\_hazards}. The class is populated with the hazards and
the string representation is produced by calling the \var{getSpec()}
function on a class instance.

\pskip

As mentioned previously, \app{uFldHazardMgr} is a strawman approach
for compiling sensor results and generating reports. The algorithm
used here is dead-simple and easily improved upon: any detection ever
made will be reported as a hazard. There is no further consideration
of follow-on passes over the same area, even if the lack of detection
may indicate that a prior initial detection was likely to be a false 
alarm.


%====================================================================
\section{Publications and Subscriptions for uFldHazardMgr}
%====================================================================
\index{uFldHazardMgr!Publications and Subscriptions}
\index{Publications and Subscriptions!uFldHazardMgr}
\label{sec_uhma_interface}

The interface for \app{uFldHazardMgr}, 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}
 $ uFldHazardMgr --interface or -i
\end{consoleverb}
\vspace{0.05in}

%====================================================================
\subsection{Variables Published by uFldHazardMgr}
\label{sec_uhma_pubs}

The primary output of \app{uFldHazardMgr} to the MOOSDB is the posting 
of requests for sensor information and the generation of hazardset 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_uhma_appcast}

\item \mvar{HAZARDSET\_REPORT}: A hazardset report summarizing the hazard
  manager's present belief about location of hazards. Section
  \ref{sec_uhma_hset_reports}.

\item \mvar{UHZ\_CONFIG\_REQUEST}: A message sent to the hazard simulator
  requesting a particular sensor configuration. Sections \ref{sec_uhma_swath}
  and \ref{sec_uhma_pd}.

\item \mvar{UHZ\_SENSOR\_REQUEST}: A message sent to
  \app{uFldHazardSensor} to request sensor/detection results be sent
  to the \app{uFldHazardMgr} as they become available. Section
  \ref{sec_uhma_detect_reports}.

\end{packed_itemize}

%====================================================================
\subsection{Variables Subscribed for by uFldHazardMgr}
\label{sec_uhma_subs}

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

\begin{packed_itemize}
\item \mvar{APPCAST\_REQ}: A request to generate and post a new
  apppcast report, with reporting criteria, and expiration.

\item \mvar{HAZARDSET\_REQUEST}: A request asking \app{uFldHazardMgr}
  to produce immediately a hazardset report. Section
  \ref{sec_uhma_hset_reports}.

\item \mvar{UHZ\_DETECTION\_REPORT}: A report sent by the
  \app{uFldHazardSensor} indicating the detection of a hazardous
  object and its location. Section \ref{sec_uhma_detect_reports}.

\item \mvar{UHZ\_CONFIG\_ACK}: A message sent by
  \app{uFldHazardSensor} confirming the requested sensor configuration
  information. Sections \ref{sec_uhma_swath} and \ref{sec_uhma_pd}.

\end{packed_itemize}

%====================================================================
\subsection*{Command Line Usage of uFldHazardMgr}
\label{sec_uhma_cmdline}
\index{Command Line Usage!uFldHazardMgr}
\index{uFldHazardMgr!Command Line Usage}

The \app{uFldHazardMgr} 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:

\vspace{0.1in}
\begin{consoleverb}
 $ uFldHazardMgr --help or -h
\end{consoleverb}
\vspace{0.1in}

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

\vspace{0.1in}
\begin{listing}{Command line usage for \app{uFldHazardMgr}}
\label{lst_uhma_usage}
\footnotesize
\begin{verbatim}
  1  ==========================================================
  2  Usage: uFldHazardMgr file.moos [OPTIONS]               
  3  ==========================================================
  4                                                            
  5  Options:                                                  
  6    --alias=&lt;ProcessName&gt;                                
  7        Launch uFldHazardMgr with the given process name. 
  8    --example, -e                                           
  9        Display example MOOS configuration block.           
 10    --help, -h                                              
 11        Display this help message.                          
 12    --interface, -i                                         
 13        Display MOOS publications and subscriptions.        
 14    --version,-v                                            
 15        Display release version of uFldHazardMgr.        
\end{verbatim}
\end{listing}
\normalsize
 
%====================================================================
\section{Terminal and AppCast Output}
%====================================================================
\label{sec_uhma_appcast}

The \app{uFldHazardMgr} application produces some useful information
to the terminal and identical content through appcasting. An example
is shown in Listing \ref{lst_uhma_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(1414)} indicates there are no configuration or run
warnings, and the current iteration of \app{uFldHazardMgr} is 1414.
Lines 4-13 convey the requested and prevailing sensor configuration
settings.

\vspace{0.1in}
\begin{listing}{Example \app{uFldHazardMgr} console output}
\label{lst_uhma_appcast}
\footnotesize
\begin{verbatim}
  1  ===================================================================
  2  uFldHazardMgr archie                                      0/0(1414)
  3  ===================================================================
  4  Config Requested:
  5      swath_width_desired: 38
  6               pd_desired: 0.86
  7     config requests sent: 118
  8                    acked: 1
  9  ------------------------ 
 10  Config Result:
 11         config confirmed: true
 12      swath_width_granted: 50
 13               pd_granted: 0.86
 14  
 15  --------------------------------------------
 16  
 17                 sensor requests: 2003
 18               detection reports: 7
 19  
 20     Hazardset Reports Requested: 1
 21        Hazardset Reports Posted: 1
 22  
 23  ===================================================================
 24  Most Recent Events (7):
 25  ===================================================================
 26  [1046.43]: New Detection, label=08, x=-14.2, y=-293.6
 27  [935.39]: New Detection, label=08, x=-14.2, y=-293.6
 28  [928.03]: New Detection, label=13, x=-59.8, y=-294.1
 29  [799.39]: New Detection, label=12, x=-150.3, y=-117.5
 30  [700.65]: New Detection, label=13, x=-59.8, y=-294.1
 31  1[525.17]: New Detection, label=15, x=-178.8, y=-234.0
 32  [522.15]: New Detection, label=01, x=-151.0, y=-217.3
\end{verbatim}
\end{listing}
\normalsize

\noindent 
Lines 17 shows the number of sensor requests sent to the hazard
sensor. This message is sent continuously so it is not surprising to
be high. Line 18 shows the number of detection reports received. Lines
20-21 show the number of time a hazardset report has been requested
and posted. The events in lines 23-32 are typically only contain the
arrival of a new detections from the sensor simulator.

%====================================================================
\section{The Jake Kasper Example Mission Using uFldHazardMgr}
%====================================================================
\label{sec_uhma_jake}

The {\em Jake Kasper} mission is distributed with the MOOS-IvP source
code and contains a ready example of the \app{uFldHazardMgr}
application, configured with hazard field in an included text file.
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 Jake Kasper} mission may be launched by:

\vspace{0.05in} 
\small
\begin{verbatim}
 $ cd moos-ivp/ivp/missions-2680/lab_10_jake_kasper_baseline
 $ ./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. 

\end{document}

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