<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%====================================================================
\section{The Echo Mission}
%====================================================================
\wikisec{grp=xmiss,file=HelmXMissEcho,short=Example Echo}

\label{exmissions_s5}

The primary purpose of the Echo example mission is to illustrate the
use of dynamically spawned behaviors. A simple behavior, the
BearingLine behavior, is used to illustrate the idea. The BearingLine
behavior simply posts a viewable point and viewable line segment
representing the bearing from the present position of the vehicle to a
fixed point in the operation area. Each new "bearing point" posted
to the \app{MOOSDB} results in a newly spawned BearingLine behavior in the
helm.

%====================================================================
\subsection{Overview of the Echo Mission Components and Topics}

\small
\begin{longtable}{|r|p{0.76\textwidth}|} \hline 
  \bsvar{Behaviors:} &amp; Waypoint, BearingLine \\ \hline
  
  \bsvar{MOOS Apps:} &amp; \app{pHelmIvP}, \app{pLogger},
  \app{uSimMarine}, \app{pMarinePID}, \app{pNodeReporter},
  \app{pMarineViewer} \\ \hline
  
  \bsvar{Primary Topics:} &amp;
  (1) The BearingLine behavior. \newline
  (2) Dynamic behavior spawning. \newline
  (3) Sending updates to the original and spawned behaviors. \\ \hline
  
  \bsvar{Side Topics:} &amp;
  (1) \app{uTimerScript} is used to auto-generate events with random 
    components that lead to behavior spawning. \newline
  (2) \app{uHelmScope} may be used to monitor the spawning and death
    of behaviors in the helm. \\ \hline
\end{longtable}
\normalsize

%====================================================================
\subsection{Launching the Echo Mission}

The echo mission may be launched from the command line:

\vspace{0.15in}
\noindent
\begin{consoleverb}
 $ cd moos-ivp/missions/s5_echo/
 $ ./launch.sh --warp=10
\end{consoleverb}
\vspace{0.15in}

\noindent
This should bring up a \app{pMarineViewer} window like that shown in
Figure \ref{fig_echo_one}, with a
single vehicle, {\em henry}, initially having the \var{"PARK"} helm
state. After hitting the \var{DEPLOY} button in the lower right
corner, the vehicle enters the \var{"SURVEYING"} mode and begins to
proceed along the waypoints as shown.

%====================================================================
\subsection{Topic \#1: The BearingLine Behavior}

In Figure \ref{fig_echo_one}, note the line segment rendered from the
vehicle in the direction of point \var{(100, -100)}. This line segment
is posted to the \app{MOOSDB} by the IvP Helm on behalf of the BearingLine
behavior. This behavior does not influence the trajectory of the
vehicle at all. The line segment acts as an easy visual confirmation
that the behavior is instantiated and running properly. In the Echo
mission this behavior is configured as in Listing
\ref{lst_echo_mission}. The bearing line originates from the present
vehicle position toward the point specified on line 8. The length of
the line is 50\% of the present distance between the vehicle and the
bearing point, as specified on line 7. The bearing point is also
configured to be rendered by the configuration on line 9.

\vspace{0.1in}
\begin{listing}{Configuration of the BearingLine behavior in the Echo example mission}
\label{lst_echo_mission}
\footnotesize
\begin{verbatim}
  1  Behavior = BHV_BearingLine
  2  {
  3    name       = bng-line
  4    templating = clone
  5    updates    = BEARING_POINT
  6  
  7         line_pct = 50
  8    bearing_point = 100,-100
  9          show_pt = true
 10  }
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The BearingLine behavior produces no (IvP) objective function, so by
the definition of the behavior run states (Section
\ref{sec_run_states}), it is never in the {\em active} state. In the
Echo mission, the BearingLine behavior is in the {\em running} state
when the vehicle is surveying the five waypoints shown in Figure
\ref{fig_echo_one}. This can be confirmed by launching a \app{uHelmScope}
window:

\vspace{0.15in}
\noindent
\begin{consoleverb}
 $ uHelmScope moos-ivp/ivp/missions/s5_echo/echo.moos -x -p}
\end{consoleverb}
\vspace{0.15in}

\noindent
The output should be similar to that shown in Listing
\ref{lst_echo_uhs_a} below. Note the Waypoint behavior is active, 
line 12, and the BearingLine behavior is in the running state, 
line 14.

\vspace{0.25in}
\begin{listing}{Output of the uHelmScope tool during the execution of the Echo mission}
\label{lst_echo_uhs_a}
\small
\begin{verbatim}
  1  ==============   uHelmScope Report  ============== DRIVE  (8)
  2    Helm Iteration: 173     (hz=0.25)(5)  (hz=0.25)(100)  (hz=0.26)(max)
  3    IvP functions:  1
  4    Mode(s):        
  5    SolveTime:      0.00    (max=0.01)
  6    CreateTime:     0.00    (max=0.01)
  7    LoopTime:       0.00    (max=0.01)
  8    Halted:         false   (0 warnings)
  9  Helm Decision: [speed,0,4,21] [course,0,359,360] 
 10    course = 189.0 
 11    speed = 2.0 
 12  Behaviors Active: ---------- (1)
 13    waypt_survey (43.0) (pwt=100.00) (pcs=6) (cpu=0.17)
 14  Behaviors Running: --------- (1)
 15    bng-line (43.0) (upd=0/0)
 16  Behaviors Idle: ------------ (1)
 17    waypt_return
 18  Behaviors Completed: ------- (0)
 19  
 20  #  MOOSDB-SCOPE ------------------------------------ (Hit '#' to en/disable)
 21  @  BEHAVIOR-POSTS TO MOOSDB ----------------------- (Hit '@' to en/disable)
\end{verbatim}
\end{listing}
\normalsize

%----------------------------------------------------------------------
\subsection{Topic \#2 Dynamic Behavior Spawning}

The Echo mission is configured to allow dynamic behavior spawning for
the BearingLine behavior. Lines 4 and 5 in Listing
\ref{lst_echo_mission} allow the spawning by configuring templating
to be enabled on line 4, and specifying the MOOS variable through
which spawning requests are received on line 5. Recall that templating
can be enabled with either the \var{"clone"} or \var{"spawn"} options.
In this case, \var{"clone"} option was chosen to allow the
instantiation of one initial instance upon helm start-up, with the
parameter configuration shown.

\vspace{0.1in}
\noindent
In this example, the \app{pMarineViewer} is configured to convert left-mouse
clicks into posts of the \mvar{BEARING\_POINT} variable to the
\app{MOOSDB}, triggering the spawning of new BearingLine instances. A
mouse click over the point \var{(-5, -58)} results in the post:


\prevgreen
\begin{verbatim}
   BEARING_POINT = "name=bng-line-5.0--158.0, bearing_point=-5.0,-158.0"
\end{verbatim}
\postverb

\noindent
The helm receives mail for the \mvar{BEARING\_POINT} variable since it
registers automatically for each variable specified in any behavior
configured with the \bvar{updates} parameter. The helm examines this
string before applying the update, and notes that the behavior name
specified is unique (not currently instantiated) and rather than
interpreting this as a request to update the existing BearingLine
behavior already instantiated, interprets it as a request to spawn a
new BearingLine instance if templating is enabled (which it is). The
new behavior is spawned, with the behavior name specified. In this
case the behavior name is based on the coordinates of the point
clicked by the user. Two successive clicks on the same point will
result in two posts to \mvar{BEARING\_POINT} by \app{pMarineViewer},
but the second post will be effectively ignored by the helm. (It is
read by the helm, but since the behavior name is one that is already
known to the helm, the update is applied to that existing behavior
instance. In this case such an update to the \bvar{bearing\_point}
parameter would be redundant.

\vspace{0.1in}
\noindent
After two such user mouse clicks, there will be two new BearingLine
behaviors instantiated, and the situation would look similar to that
shown in Figure \ref{fig_echo_two}. If the uHelmScope tool is still
connected as above, the output would looks similar to that shown
in Listing \ref{lst_echo_uhs_b}. Note the existence of three running
BearingLine behavior instances reported in lines 15-17. The instance
on line 15 was created upon helm startup, and the instances on lines
16-17 were created upon the user mouse clicks.


\vspace{0.25in}
\begin{listing}{Output of the uHelmScope tool during the later execution of the Echo mission}
\label{lst_echo_uhs_b}
\small
\begin{verbatim}
  1  ==============   uHelmScope Report  ============== DRIVE  (12)
  2    Helm Iteration: 279     (hz=0.25)(5)  (hz=0.25)(100)  (hz=0.26)(max)
  3    IvP functions:  1
  4    Mode(s):        ACTIVE:SURVEYING
  5    SolveTime:      0.00    (max=0.01)
  6    CreateTime:     0.00    (max=0.01)
  7    LoopTime:       0.00    (max=0.01)
  8    Halted:         false   (0 warnings)
  9  Helm Decision: [speed,0,4,21] [course,0,359,360] 
 10    course = 180.0 
 11    speed = 2.0 
 12  Behaviors Active: ---------- (1)
 13    waypt_survey (69.6) (pwt=100.00) (pcs=4) (cpu=0.28)
 14  Behaviors Running: --------- (3)
 15    bng-line (69.6) (upd=0/0)
 16    bng-line-5--58 (66.1) (upd=1/1)
 17    bng-line13--124 (56.8) (upd=1/1)
 18  Behaviors Idle: ------------ (1)
 19    waypt_return
 20  Behaviors Completed: ------- (0)
 21  
 22  #  MOOSDB-SCOPE ------------------------------------ (Hit '#' to en/disable)
 23  @  BEHAVIOR-POSTS TO MOOSDB ----------------------- (Hit '@' to en/disable)
\end{verbatim}
\end{listing}
\normalsize

%============================================================================
\subsection{Topic \#3: Sending Updates to the Original and Spawned Behaviors}
\label{echo_topic3}

The action associated with the left-mouse click in the Echo mission is
configured in the \app{pMarineViewer} configuration block in
\var{echo.moos} by:

\prevblue
\begin{verbatim}
  left_context[bng_point] = BEARING_POINT = name=bng-line$(X)-$(Y) # bearing_point=$(X),$(Y)
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
Setting the context for the left and right mouse clicks in
\app{pMarineViewer} is is achieved by utilizing the Mouse Context
feature of \app{pMarineViewer}, discussed in the \app{pMarineViewer}
documentation, \cite{url_pmv}, in the section {\em "Contextual Mouse
  Poking with Embedded OpArea Information"}.  With the above
configuration a left-mouse click may result in the following if
clicked at the point \var{(-5, -58)}:

\prevgreen
\begin{verbatim}
  BEARING_POINT = name=bng-line-5--58 # bearing_point=-5,-58
\end{verbatim}
\postverb

\noindent
Updating or changing the prevailing parameters for existing behaviors
is possible via the use of the MOOS variable specified in the
\bvar{updates} parameter for each behavior. The only difference
between an update that changes parameters of an existing behavior, and
an update that spawns a new behavior is the inclusion of a
\var{name=&lt;behavior-name&gt;} as above. If this component is present in
the string posted to the \app{MOOSDB} and the \var{&lt;behavior-name&gt;}
specifies an existing behavior, then that behavior only will have its
parameters updated. If it does not specify an existing behavior, a new
behavior will be spawned with the specified name. If the
\var{name=&lt;behavior-name&gt;} component is not included in the posting,
then the update will be applied to all behaviors configured to receive
updates via that particular MOOS variable.

\vspace{0.1in}
\noindent
This case is a bit interesting since all newly spawned behaviors
specify the same MOOS variable for receiving updates. Indeed a single
poke to the MOOS variable \mvar{BEARING\_POINT} could result in the
simultaneous configuration modification of all instantiated
BearingLine behaviors. In the Echo mission, \app{pMarineViewer} is
configured to make the following pokes to the \app{MOOSDB} via the
\var{ACTION} pull-down menu:

\prevblue
\begin{verbatim}
  action  = BEARING_POINT = show_pt=true
  action+ = BEARING_POINT = show_pt=false
  action  = BEARING_POINT = line_pct=0
  action  = BEARING_POINT = line_pct=25
  action  = BEARING_POINT = line_pct=50
  action  = BEARING_POINT = line_pct=75
  action+ = BEARING_POINT = line_pct=100
  action  = BEARING_POINT = "name=bng-line # line_pct=0"
  action  = BEARING_POINT = "name=bng-line # line_pct=50"
  action  = BEARING_POINT = "name=bng-line # line_pct=100"
\end{verbatim}
\postverb

\noindent
The first two actions will turn on or off the rendering of the bearing
points posted by each behavior. The next five actions will adjust the
rendering length of the posted bearing line by each behavior. The last
two actions will adjust the rendering length of the posted bearing
line only for the behavior named \var{"bng-line"}, the behavior spawned
at the time of helm start-up.

\subsection{Suggestions for Tinkering}

\begin{itemize}
\item After the mission is launched, use the \var{ACTION} pull-down
  menu in \app{pMarineViewer} to select \msvar{AUTO\_SPAWN=true}. This
  enables a script via \app{uTimerScript} that automatically generates
  new bearing points, spawning new behaviors. These behaviors have
  their durations set randomly by the script to be in range $[5,10]$
  seconds. Note the new bearing lines emerging and moving with the
  vehicle until the behavior dies. The script will lead to the
  spawning (and death) of 5000 behaviors over the course of about two
  hours of simulation at \pvar{MOOSTimeWarp=1}.

\item With \msvar{AUTO\_SPAWN=true} as above, let the vehicle return to
  the launch point (by clicking the \var{RETURN} button in the
  \app{pMarineViewer} window. After it reaches the return point and
  perhaps sits for a bit, hit the \var{DEPLOY} button once again to
  return the vehicle into its \var{SURVEYING} mode. Notice that
  initially there are many bearing lines rendered before returning to
  only a handful of bearing lines after a few seconds of simulation.
  This is because newly spawned behaviors do not start their duration
  clock until the first time the behavior enters the running state.
  All behaviors spawned while returning to the start point are
  effectively put on hold until the vehicle is re-deployed. Then they
  all start their duration clocks simultaneously and all die off
  5-10 seconds later.
\end{itemize}

\newpage
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/echo_one.png}
  \caption{{\bf The Echo Mission (1):} The vehicle \var{"henry"}
    traverses waypoints with the Waypoint behavior. The BearingLine
    behavior generates a viewable "bearing point" at \vvar{(100,
      -100)}, and a viewable "bearing line".}
\label{fig_echo_one}
\end{figure}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.935\textwidth]{figures/echo_two.png}
  \caption{{\bf The Echo Mission (2):} The user has clicked two new
    bearing points, \vvar{(-5, -58)}, and \vvar{(13, -124)}, and two
    new BearingLine behaviors have been spawned, each generating
    bearing line and bearing point visual outputs.}
\label{fig_echo_two}
\end{figure}
</pre></body></html>