<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{uTimerScript: Scripting Events to the MOOSDB}
\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}
\labsrc{project-pavlab/appdocs/app\_utscript} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UTimerScript}
\wikidoc{bugz=uTimerScript}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
\section{Overview}
%===================================================================
\label{sec_uts}
%\index{uTimerScript}

The \app{uTimerScript} application allows the user to script a set of
pre-configured posts to a \app{MOOSDB}. In its most basic form, it may
be used to initialize a set of variables to the \app{MOOSDB}, and
immediately terminate itself if a quit event is included. The
following configuration block, if placed in the alpha example mission,
would mimic the posts to the \app{MOOSDB} behind the \var{DEPLOY}
button, simply disabling manual control, deploying the vehicle and
quitting the script: Listing \ref{sec_uts}.\ref{lst_test}.

\vspace{0.2in}

\begin{listing}{A Simple Timer Script}
\label{lst_test}
\begin{verbatim}
 1  ProcessConfig = uTimerScript  
 2  {
 3    event = var=MOOS_MANUAL_OVERIDE, val=false
 4    event = var=DEPLOY, val=true
 5    event = quit 
 6  }
\end{verbatim}
\end{listing}
\vspace{0.2in}

\noindent
Additionally, \app{uTimerScript} may be used with the following
advanced functions:

\begin{packed_itemize}
\item Each entry in the script may be scheduled to occur after a
  specified amount of elapsed time.
\item Event timestamps may be given as an exact point in time relative
  to the start of the script, or a range in times with the exact time
  determined randomly at run-time.
\item The execution of the script may be paused, or fast-forwarded a
  given amount of time, or forwarded to the next event on the script
  by writing to a MOOS variable.
\item The script may be conditionally paused based on user defined logic
  conditions over one or more MOOS variables.
\item The variable value of an event may also contain information
  generated randomly. 
\item The script may be reset or repeated any given number of times.
\item The script may use its own time warp, which can be made to vary
  randomly between script executions.
\end{packed_itemize}

\noindent
In short, \app{uTimerScript} may be used to effectively simulate the
output of other MOOS applications when those applications are not
available. A few examples are provided, including a simulated GPS unit
and a crude simulation of wind gusts.

%===================================================================
\section{Using uTimerScript}
%===================================================================

Configuring a script minimally involves the specification of one or
more events, with an event comprising of a MOOS variable and value to
be posted and an optional time at which it is to be posted. Scripts
may also be reset on a set policy, or from a trigger by an external
process.

%===================================================================
\subsection{Configuring the Event List}
%\index{uTimerScript!Configuring the Event List}
\label{sec_uts_events}

The event list or script is configured by declaring a set of event
entries with the following format:

\vspace{0.1in}
  \pvar{event} \psvar{= var=&lt;MOOSVar&gt;, val=&lt;value&gt;, [time=&lt;time-of-event&gt;]}
\vspace{0.1in}

\noindent
The keywords \pvar{event}, \var{var}, \var{val}, and \var{time} are not
case sensitive, but the values \var{&lt;moos-variable&gt;} and
\var{&lt;var-value&gt;} are case sensitive. The \var{&lt;var-value&gt;} type is
posted either as a string or double based on the following heuristic:
if the \var{&lt;var-value&gt;} has a numerical value it is posted as a
double, and otherwise posted as a string. If one wants to post a
string with a numerical value, putting quotes around the number
suffices to have it posted as a string. Thus \var{val=99} posts a
double, but \var{var="99"} posts a string. If a string is to be posted
that contains a comma such as \var{"apples, pears"}, one must put the
quotes around the string to ensure the comma is interpreted as part of
\var{&lt;var-value&gt;}. The value field may also contain one or more macros
expanded at the time of posting, as described in Section
\ref{uts_macros}.

%===================================================================
\subsection{Setting the Event Time or Range of Event Times}

The value of \var{&lt;time-of-event&gt;} is given in seconds and must be a
numerical value greater or equal to zero. The time represents the
amount of elapsed time since the \app{uTimerScript} was first launched
and un-paused. The list of events provided in the configuration block
need not be in order - they will be ordered by the \app{uTimerScript}
utility. The \var{&lt;time-of-event&gt;} may also be specified by a interval
of time, e.g., \var{time=0:100}, such that the event may occur at some
point in the range with uniform probability. The only restrictions are
that the lower end of the interval is greater or equal to zero, and
less than or equal to the higher end of the interval. By default the
timestamps are calculated once from their specified interval, at the
the outset of \app{uTimerScript}. The script may alternatively be
configured to recalculate the timestamps from their interval each time
the script is reset, by setting the \pvar{shuffle} parameter to true. This
parameter, and resetting in general, are described in the next Section
\ref{sec_uts_reset}.

%===================================================================
\subsection{Resetting the Script}
\label{sec_uts_reset}
%\index{uTimerScript!Resetting}

The timer script may be reset to its initial state, resetting the
stored elapsed-time to zero and marking all events in the script as
pending. This may occur either by cueing from an event outside
\app{uTimerScript}, or automatically from within
\app{uTimerScript}. Outside-cued resets can be triggered by posting
\mvar{UTS\_RESET} with the value \var{="reset"}, or \var{"true"}.  The
\pvar{reset\_var} parameter names a MOOS variable that may be used as
an alternative to \mvar{UTS\_RESET}.  It has the format:

\vspace{0.1in}
  \pvar{reset\_var} \psvar{= &lt;moos-variable&gt;  // Default is UTS\_RESET}
\vspace{0.1in}
\normalsize

\noindent
The script may be also be configured to auto-reset after a certain
amount of time, or immediately after all events are posted, using the
\pvar{reset\_time} parameter. It has the format:

\vspace{0.1in}
   \pvar{reset\_time = &lt;time-or-condition&gt;  // Default is "none"}
\vspace{0.1in}

\noindent
The \var{&lt;time-or-condition&gt;} may be set to \var{"all-posted"} which
will reset after the last event is posted. If set to a numerical value
greater than zero, it will reset after that amount of elapsed time,
regardless of whether or not there are pending un-posted events. If
set to \var{"none"}, the default, then no automatic resetting is
performed. Regardless of the \pvar{reset\_time} setting, prompted resets
via the \mvar{UTS\_RESET} variable may take place when cued.

\vspace{0.1in}
\noindent
The script may be configured to accept a hard limit on the number of
times it may be reset. This is configured using the \pvar{reset\_max}
parameter and has the following format:

\vspace{0.1in}
  \pvar{reset\_max = &lt;amount&gt;   // Default is "nolimit"}
\vspace{0.1in}

\noindent
The \var{&lt;amount&gt;} specified may be any number greater or equal to
zero, where the latter, in effect, indicates that no resets are
permitted. If unlimited resets are desired (the default), the case
insensitive argument \var{"unlimited"} or \var{"any"} may be used.

\vspace{0.1in}
\noindent
The script may be configured to recalculate all event timestamps
specified with a range of values whenever the script is reset.  This
is done with the following parameter:

\vspace{0.1in}
  \pvar{shuffle = false   // Default is "true"}
\vspace{0.1in}

The script may be configured to reset or restart each time it
transitions from a situation where its conditions are not met to a
situation where its conditions are met, or in other words, when the
script is "awoken". The use of logic conditions is described in more
detail in Section \ref{sec_uts_pause}.  This is done with the following
parameter:

\vspace{0.1in}
  \pvar{upon\_awake} \psvar{= restart   // Default is "n/a", no action}
\vspace{0.1in}

\noindent
Note that this does not apply when the script transitions from being
paused to un-paused as described in Section \ref{sec_uts_pause}.  See
the example in Section \ref{uts_example_gps} for a case where the
\pvar{upon\_awake} feature is handy.

%===================================================================
\section{Script Flow Control}
%===================================================================
\label{uts_flow_control}
%\index{uTimerScript!Script Flow Control}

The script flow may be affected in a number of ways in addition to the
simple passage of time. It may be (a) paused by explicitly pausing it,
(b) implicitly paused by conditioning the flow on one or more logic
conditions, (c) fast-forwarded directly to the next scheduled event,
or fast-forwarded some number of seconds. Each method is described in
this section.

%===================================================================
\subsection{Pausing the Timer Script}
\label{sec_uts_pause}
%\index{uTimerScript!Script Flow Control}
%\index{uTimerScript!Pausing the Script}

The script can be paused at any time and set to be paused initially at
start time.  The \pvar{paused} parameter affects whether the timer
script is actively unfolding at the outset of launching
\app{uTimerScript}. It has the following format:

\vspace{0.1in}
  \pvar{paused} \psvar{= &lt;Boolean&gt;}
\vspace{0.1in}

\noindent 
The keyword \pvar{paused} and the string representing the Boolean are
not case sensitive. The Boolean simply must be either \var{"true"} or
\var{"false"}. By setting \pvar{paused} to true, the elapsed time
calculated by \app{uTimerScript} is paused and no variable-value pairs
will be posted. When un-paused the elapsed time begins to accumulate
and the script begins or resumes unfolding. The default value of
\pvar{paused} is false.

\vspace{0.1in}
\noindent
The script may also be paused through the MOOS variable
\mvar{UTS\_PAUSE} which may be posted by some other MOOS
application. The values recognized are \var{"true"}, \var{"false"}, or
\var{"toggle"}, all case insensitive. The name of this variable may be
substituted for a different one with the \pvar{pause\_var} parameter in
the \app{uTimerScript} configuration block. It has the format:

\vspace{0.1in}
  \pvar{pause\_var} \psvar{= &lt;MOOSVar&gt;    // Default is UTS\_PAUSE}
\vspace{0.1in}

\noindent
If multiple scripts are being used (with multiple instances of
\app{uTimerScript} connected to the \app{MOOSDB}), setting the
\pvar{pause\_var} to a unique variable may be needed to avoid
unintentionally pausing or un-pausing multiple scripts with single
write to \mvar{UTS\_PAUSE}.

%===================================================================
\subsection{Conditional Pausing of the Timer Script and Atomic Scripts}
\label{sec_uts_logic}
%\index{uTimerScript!Script Flow Control}
%\index{uTimerScript!Conditional Pausing}
%\index{uTimerScript!Logic Conditions}
%\index{uTimerScript!Pausing the Script with Conditions}

The script may also be configured to condition the "paused-state" to
depend on one or more logic conditions. If conditions are specified in
the configuration block, the script must be both un-paused as
described above in Section \ref{sec_uts_pause}, and all specified logic
conditions must be met in order for the script to begin or resume
proceeding. The logic conditions are configured as follows:

\vspace{0.1in}
  \pvar{condition} \psvar{= &lt;logic-expression&gt;}
\vspace{0.1in}

\noindent 
The \var{&lt;logic-expression&gt;} syntax is described in Logic Appendix,
and may involve the simple comparison of MOOS variables to specified
literal values, or the comparison of MOOS variables to one
another. See the script configuration in Section \ref{uts_example_gps}
for one example usage of logic expressions.

%\index{uTimerScript!Atomic Scripts}

\vspace{0.1in}
\noindent
An {\em atomic} script is one that does not check conditions once it has
posted its first event, and prior to posting its last event. Once a
script has started, it is treated as unpausable with respect to the
the logic conditions. This is configured with:

\vspace{0.1in}
  \pvar{script\_atomic} \psvar{= &lt;Boolean&gt;}
\vspace{0.1in}

\noindent
It can however be paused and unpaused via the pause variable, e.g.,
\mvar{UTS\_PAUSE}, as described in Section \ref{sec_uts_pause}. If the
logic conditions suddenly fail in an atomic script midway, the check
is simply postponed until after the script completes and is perhaps
reset. If the conditions in the meanwhile revert to being satisfied,
then no interruption should be observable.

%===================================================================
\subsection{Fast-Forwarding the Timer Script}
\label{sec_uts_jump}
%\index{uTimerScript!Script Flow Control}
%\index{uTimerScript!Jumping To the Next Event}
%\index{uTimerScript!Fast Forwarding in Time}
%\index{uTimerScript!Configuration Parameters}

The timer script, when un-paused, moves forward in time with events
executed as their event times arrive. However, the script may be moved
forwarded by writing to the MOOS variable \mvar{UTS\_FORWARD}. If the
value received is zero (or negative), the script will be forwarded
directly to the point in time at which the next scheduled event
occurs. If the value received is positive, the elapsed time is
forwarded by the given amount. Alternatives to the MOOS variable
\mvar{UTS\_FORWARD} may be configured with the parameter:

\vspace{0.1in}
  \pvar{forward\_var} \psvar{= &lt;MOOSVar&gt;   // Default is UTS\_FORWARD}
\vspace{0.1in}

\noindent
If multiple scripts are being used (with multiple instances of
\app{uTimerScript} connected to the \app{MOOSDB}), setting the
\pvar{forward\_var} to a unique variable may be needed to avoid
unintentionally fast forwarding multiple scripts with single write to
\mvar{UTS\_FORWARD}.

%===================================================================
\subsection{Quitting the Timer Script}
\label{sec_uts_quit}
%\index{uTimerScript!Script Flow Control}
%\index{uTimerScript!Quitting}
%\index{uTimerScript!Exiting}
%\index{uTimerScript!Configuration Parameters}

The timer script may be configured with a special event, the {\em
  quit} event, resulting in disconnection with the \app{MOOSDB} and a
process exit. This is done with the configuration:

\vspace{0.1in}
  \pvar{event} \psvar{= quit [time=&lt;time-of-event&gt;]}
\vspace{0.1in}

\noindent
Before quitting, a final posting to the \app{MOOSDB} is made with the
variable \mvar{EXITED\_NORMALLY}. The value is \app{"uTimerScript"},
or its alias if an alias was used. This indicates to any other
watchdog process, such as \app{uProcessWatch}, that the exiting of
this script is not a reason for concern. When \app{uTimerScript}
receives its own posting in the next incoming mail, it assumes all
pending posts have been made and will then quit.

%===================================================================
\section{Macro Usage in Event Postings}
%===================================================================
\label{uts_macros}
%\index{uTimerScript!Macros}

Macros may be used to add a dynamic component to the value field of an
event posting. This substantially expands the expressive power and
possible uses of the \app{uTimerScript} utility.  Recall that the
components of an event are defined by:

\vspace{0.1in}
  \pvar{event} \psvar{= var=&lt;MOOSVar&gt;, val=&lt;var-value&gt;, time=&lt;time-of-event&gt;}
\vspace{0.1in}

The \var{&lt;var-value&gt;} component may contain a macro of the form
\var{\$[MACRO]}, where the macro is either one of a few built-in
macros available, or a user-defined macro with the ability to
represent random variables. Macros may also be combined in simple
arithmetic expressions to provide further expressive power. In each
case, the macro is expanded at the time of the event posting,
typically with different values on each successive posting.

%===================================================================
\subsection{Built-In Macros Available}
\label{uts_macros_builtin}
%\index{uTimerScript!Macros Built-In}

There are five built-in macros available:

\vspace{0.1in}
\noindent
\begin{packed_itemize}
\item \bvar{\$[DBTIME]}: The estimated time since the \app{MOOSDB}
  started, similar to the value in the MOOS variable \mvar{DB\_UPTIME}
  published by the \app{MOOSDB}.
\end{packed_itemize}

\vspace{0.1in}
\noindent
An example usage:

\vspace{0.1in}
  \pvar{event} \psvar{= var=DEPLOY\_RECEIVED, val=\$[DBTIME], time=10:20}
\vspace{0.1in}

\noindent
\begin{packed_itemize}
\item \bvar{\$[UTCTIME]}: The UTC time, in seconds, at the time of the posting.
\item \bvar{\$[UTC]}: The UTC time, in seconds, at the time of the posting.
\item \bvar{\$[COUNT]}: Expands to the integer total of all posts thus
  far in the current execution of the script, and is reset to zero
  when the script resets.
\item \bvar{\$[TCOUNT]}: Expands to the integer total of all posts thus
  far since the application began, i.e., it is a running total that is
  not reset when the script is reset.
\item \bvar{\$[IDX]}: Expands to the integer value representing an
  event's count or index into the sequence of events. However, it will
  always post as a string and will be padded with zeros to the left,
  e.g., \var{"000", "001", ...}, and so on.
\end{packed_itemize}

\vspace{0.1in}
\noindent
If the value of a MOOS posting is solely a macro, the variable type of
the posting is a double, not a string. For example
\psvar{val=\$[DBTIME]} will post a type double, whereas
\psvar{val="time:\$[DBTIME]"} will post a type string.

%===================================================================
\subsection{User Configured Macros with Random Variables}
\label{sec_uts_randvars}
%\index{uTimerScript!Random Variables}

Further macros are available for use in the \var{&lt;var-value&gt;}
component of an event, defined and configured by the user, and based
on the idea of a random variable. In short, the macro may expand to a
numerical value chosen within a user specified range, and recalculated
according to a user-specified policy. The general format is:

\vspace{0.1in}
  \pvar{rand\_var} \psvar{= varname=&lt;variable&gt;, min=&lt;value&gt;, max=&lt;value&gt;, key=&lt;key\_name&gt;}
\vspace{0.1in}

\noindent
The \var{&lt;variable&gt;} component defines the macro name.  The
\var{&lt;low\_value&gt;} and \var{&lt;high\_value&gt;} components define the range
from which the random value will be chosen uniformly. The
\var{&lt;key\_name&gt;} determines when the random value is reset. It must
be set to one of the following three values: \var{"at\_start"},
\var{"at\_reset"}, and \var{"at\_post"}. Random variables with the key
name \var{"at\_start"} are assigned a random value only at the start
of the \app{uTimerScript} application. Those with the
\var{"at\_reset"} key name also have their values re-assigned whenever
the script is reset. Those with the \var{"at\_post"} key name also
have their values re-assigned after any event is posted.

%===================================================================
\subsection{Support for Simple Arithmetic Expressions with Macros}

Macros that expand to numerical values may be combined in simple
arithmetic expressions with other macros or scalar values. The general
form is:

\vspace{0.1in}
%\index{uTimerScript!Arithmetic Expressions}
\small
\begin{verbatim}
  {&lt;value&gt; &lt;operator&gt; &lt;value&gt;} 
\end{verbatim}
\normalsize

\vspace{0.1in}
\noindent
The \var{&lt;value&gt;} components may be either a scalar or a macro, and
the \var{&lt;operator&gt;} component may be one of \var{'+'}, \var{'-'},
\var{'*'}, \var{'/'}. Nesting is also supported. Below are some
examples:

\vspace{0.1in}
\small
\begin{verbatim}
  {$[FOOBAR] * 0.5}
  {-2-$[FOOBAR]}
  {$[APPLES] + $[PEARS]}
  {35 / {$[FOOBAR]-2}}
  {$[DBTIME] - {35 / {$[UTCTIME]+2}}}
\end{verbatim}
\normalsize

\vspace{0.1in}
\noindent
If a macro should happen to expand to a string rather than a double
(numerical) value, the string evaluates to zero for the sake of the
remaining evaluations.

%===================================================================
\section{Time Warps, Random Time Warps, and Restart Delays}
%===================================================================
\label{sec_uts_time_warp}

A time warp and initial start delay may be optionally configured into
the script to change the event schedule without having to edit all the
time entries for each event. They may also be configured to take on a
new random value at the outset of each script execution to allow for
simulation of events in nature or devices having a random component.

%===================================================================
\subsection{Random Time Warping}
\label{sec_uts_random_time_warp}
%\index{uTimerScript!Time Warp}

The time warp is a numerical value in the range $(0, \infty]$, with a
default value of $1.0$. Lower values indicate that time is moving more
slowly. As the script unfolds, a counter indicating
\var{"elapsed\_time"} increases in value as long as the script is not
paused. The \var{"elapsed\_time"} is multiplied by the time warp
value. The time warp may be specified as a single value or a range of
values as below:

%\index{uTimerScript!Time Warp}
%\index{Time Warp!uTimerScript}

\prevblue
\begin{verbatim}
  time_warp = &lt;value&gt;
  time_warp = &lt;low-value&gt;:&lt;high-value&gt;
\end{verbatim}
\postverb

\noindent
When a range of values is specified, the time warp value is calculated
at the outset, and re-calculated whenever the script is reset. See the
example in Section \ref{uts_example_wind} for a use of random time
warping to simulate random wind gusts.

%===================================================================
\subsection{Random Initial Start and Reset Delays}
\label{sec_uts_start_delay}
%\index{uTimerScript!Start Delays}
%\index{uTimerScript!Restart Delays}

A start delay may be provided with the \pvar{delay\_start} parameter,
given in seconds in the range $[0, \infty]$, with a default value of
$0$. The effect of having a non-zero delay of $n$ seconds is to have
\var{elapsed\_time=n} at the outset of the script, on the first time
through the script only. Thus a delay of $n$ seconds combined with a
time warp of $0.5$ would result in observed delay of $2*n$
seconds. The start delay may be specified as a single value or a range
of values as below:

%\index{uTimerScript!Start Delay}
%\index{Start Delay!uTimerScript}

\prevblue
\begin{verbatim}
    delay_start = &lt;value&gt;
    delay_start = &lt;low-value&gt;:&lt;high-value&gt;
\end{verbatim}
\postverb

\noindent
To specify a delay applied at the beginning if the script {\em after
a reset}, use the \pvar{delay\_reset} parameter instead. 

\prevblue
\begin{verbatim}
    delay_reset = &lt;value&gt;
    delay_reset = &lt;low-value&gt;:&lt;high-value&gt;
\end{verbatim}
\postverb

\noindent
When a range of values is specified, the start ore reset delay value
is calculated at the outset, and re-calculated whenever the script is
reset. See the example in Section \ref{uts_example_gps} for a use of
random start delays to the simulate the delay in acquiring satellite
fixes in a GPS unit on an UUV coming to the surface.

%===================================================================
\subsection{Status Messages Posted to the MOOSDB by uTimerScript}
\label{sec_uts_status}
%\index{uTimerScript!Status Messages}

The \app{uTimerScript} periodically publishes a string to the MOOS
variable \mvar{UTS\_STATUS} indicating the status of the script.
This variable will be published on each iteration if one of the
following conditions is met: (a) two seconds has passed since the
previous status message posted, or (b) an event has been been posted,
or (c) the paused state has changed, or (d) the script has been reset,
or (e) the state of script logic conditions has changed. A posting may 
look something like:

\prevgreen
\begin{verbatim}
  UTS_STATUS = "name=RND_TEST, elapsed_time=2.00, posted=1, pending=5, paused=false, 
               conditions_ok=true, time_warp=3, start_delay=0, shuffle=false, 
               upon_awake=restart, resets=2/5"
\end{verbatim}
\postverb

\noindent
In this case, the script has posted one of six events (\var{posted=1,
  pending=5}). It is actively unfolding, since \var{paused=false}
(Section \ref{sec_uts_pause}) and \var{conditions\_ok=true} (Section
\ref{sec_uts_logic}). It has been reset twice out of a maximum of five
allowed resets (\var{resets=2/5}, Section \ref{sec_uts_reset}). Time
warping is being deployed \var{time\_warp=3} (Section
\ref{sec_uts_time_warp}), there is no start delay in use
\var{start\_delay=0} (Section \ref{sec_uts_start_delay}). The shuffle
feature is turned off \var{shuffle=false} (Section
\ref{sec_uts_reset}). The script is not configured to reset upon
re-entering the un-paused state, \var{awake\_reset=false} (Section
\ref{sec_uts_reset}).

\vspace{0.1in}
\noindent
When multiple scripts are running in the same MOOS community, one may
want to take measures to discern between the status messages generated
across scripts. One way to do this is to use a unique MOOS variable
other than \mvar{UTS\_STATUS} for each script. The variable used for
publishing the status may be configured using the \pvar{status\_var}
parameter. It has the following format:

\vspace{0.1in}
  \pvar{status\_var} \psvar{= &lt;MOOSVar&gt;  // Default is UTS\_STATUS}
\vspace{0.1in}

\noindent
Alternatively, a unique name may be given to each to each script. All
status messages from all scripts would still be contained in postings
to \mvar{UTS\_STATUS}, but the different script output could
be discerned by the name field of the status string. The script name
is set with the following format.

\vspace{0.1in}
  \pvar{script\_name} \psvar{= &lt;string&gt;  // Default is "unnamed"}
\vspace{0.05in}

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

The script configuration and progress of script execution may also be
monitored from an open console window where \app{uTimerScript} is
launched, or through an appcast viewer.  Example output is shown below
in Listing \ref{lst_uts_appcast}.  On line 2, the name of the local
community or vehicle name is listed on the left. On the right,
\var{"0/0(450)} indicates there are no configuration or run warnings,
and the current iteration of \app{uFldTimerScript} is 450.

%===================================================================
\subsection*{Lines 4-16: Script Configuration}

Lines 4-11 show the script configuration. Line 5 shows the number of
elements in the script and in parentheses the last element to have
been posted. Line 6 shows the number of times the script has
restarted.  Line 7 shows the present time warp and the range of time
warps possible on each script restart in brackets (Section
\ref{sec_uts_random_time_warp}. Lines 8-9 show the delay applied at
the start and after a script reset (Section
\ref{sec_uts_start_delay}). Line 10 indicates the script is presently
not paused (Section \ref{sec_uts_pause}). Line 11 indicates the script
presently meets any prevailing logic conditions (Section
\ref{sec_uts_logic}). Lines 13-16 show that there are two random
variables defined for this script that may be used in event
definitions. They are both uniform random variables. The first varies
over possible directions, and the second over possible speed
magnitudes. Section \ref{sec_uts_randvars}.

\vspace{0.25in}
\begin{listing}{Example uTimerScript console and appcast output}
\label{lst_uts_appcast}
\footnotesize
\begin{verbatim}
   1  ===================================================================
   2  uTimerScript charlie                                       0/0(450)
   3  ===================================================================
   4  Current Script Information: 
   5      Elements: 10(8)
   6       Reinits: 2
   7     Time Warp: 1.09 [0.2,2]
   8   Delay Start: 0
   9   Delay Reset: 23.66 [10,60]
  10        Paused: false
  11  ConditionsOK: true
  12  
  13  RandomVar  Type     Min  Max  Parameters
  14  ---------  -------  ---  ---  ----------
  15  ANG        uniform  0    359            
  16  MAG        uniform  1.5  3.5            
  17  
  18  P/Tot  P/Loc  T/Total   T/Local  Variable/Var
  19  -----  -----  --------  -------  ------------
  20  19     9      196.77    72.15    DRIFT_VECTOR_ADD = 193,-0.6
  21  20     0      219.42    24.08    DRIFT_VECTOR_ADD = 12,0.4
  22  21     1      220.93    25.71    DRIFT_VECTOR_ADD = 12,0.4
  23  22     2      222.95    27.91    DRIFT_VECTOR_ADD = 12,0.4
  24  23     3      224.96    30.09    DRIFT_VECTOR_ADD = 12,0.4
  25  24     4      226.46    31.73    DRIFT_VECTOR_ADD = 12,0.4
  26  25     5      228.47    33.91    DRIFT_VECTOR_ADD = 12,-0.4
  27  26     6      230.49    36.10    DRIFT_VECTOR_ADD = 12,-0.4
  28  
  29  ===================================================================
  30  Most Recent Events (3):
  31  ===================================================================
  32  [192.78]: Script Re-Start. Warp=0.48922, DelayStart=0.0, DelayReset=54.1
  33  [44.80]: Script Re-Start. Warp=1.61692, DelayStart=0.0, DelayReset=18.9
  34  [0.51]: Script Start. Warp=1, DelayStart=0.0, DelayReset=0.0
\end{verbatim}
\end{listing}
\normalsize

%===================================================================
\subsection*{Lines 18-27: Recent Script Postings}

Lines 18-27 show recent postings to the \app{MOOSDB} by the script. The
first column shows the total postings so far for the script. The
second column shows the index within the script. In the above example,
there are ten elements in the script. The most recent posting on line
27, shows the script has been reset twice and the most recent posting is
of the seventh element of the script (index 6). The third column shows the
total time since script started, and the fourth column shows the time 
since the script was re-started. Note the time delay between lines 20 and
21, due to the \pvar{delay\_reset} shown on line 9. The last column shows
the actual variable value pair posted.

%===================================================================
\subsection*{Lines 29-34: Recent Events}

Lines 29-34 show recent events (other than event postings). In this
case it shows the script has been started, and re-started twice. Notice
the delay reset on line 32 is different than that on line 9.  The
delay reset time of 23.66 seconds shown on line 9 is the delay reset
to be applied on the {\em next} reset.

%===================================================================
\section{Configuration Parameters for uTimerScript}
%===================================================================
%\index{uTimerScript!Configuration Parameters}
%\index{Configuration Parameters!uTimerScript}

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for uTimerScript}
\label{lst_pmv_params_utscript}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 

  \pvar{block\_on}: &amp; A comma-separated list of MOOS apps on which the 
  script will block until seen in the list of \var{DB\_CLIENTS}. \\
  
  \pvar{condition}: &amp; A logic condition that must be met for the script
  to be un-paused. Section \ref{sec_uts_logic}. \\
  
  \pvar{delay\_reset}: &amp; Number of seconds added to each event time,
  on each script reset. Legal values: any non-negative numerical
  value, or range of values separated by a colon. The default is
  zero. Section \ref{sec_uts_start_delay}. \\
      
  \pvar{delay\_start}: &amp; Number of seconds, or range of seconds, added
  to each event time, on first pass only. Legal values: any non-negative
  numerical value, or range of values separated by a colon. The default is 
  zero. Section \ref{sec_uts_start_delay}. \\
      
  \pvar{event}: &amp; A description of a single event in the timer
  script. Section \ref{sec_uts_events}. \\
  
  \pvar{forward\_var}: &amp; A MOOS variable for taking cues to forward
  time. The default is \mvar{UTS\_FORWARD}). Section
  \ref{sec_uts_jump}. \\
  
  \pvar{paused}: &amp; A Boolean indicating whether the script is paused upon
  launch. Legal values: true, false. The default is false. Section 
  \ref{sec_uts_pause}. \\
  
  \pvar{pause\_var}: &amp; A MOOS variable for receiving pause state cues
  (\mvar{UTS\_PAUSE}). Section \ref{sec_uts_pause}. \\
  
  \pvar{rand\_var}: &amp; A declaration of a random variable macro to be 
  expanded in event values. Section \ref{sec_uts_randvars}. \\
  
  \pvar{reset\_max}: &amp; The maximum amount of resets allowed. Legal
  values: any non-negative integer, or the string \var{"nolimit"}. The
  default is \var{"nolimit"}. NOTE: If re-setting is desired, the
  \pvar{reset\_time} parameter must also be changed from its default
  value of \var{"none"}. Section \ref{sec_uts_reset}. \\
  
  \pvar{reset\_time}: &amp; The time or condition when the script is reset
  Legal values: Any non-negative number, the string \var{"none"}, or
  \var{"all-posted"}, or equivalently, \var{"end"}. The default is
  \var{"none"}.  Section \ref{sec_uts_reset}. \\
  
  \pvar{reset\_var}: &amp; A MOOS variable for receiving reset cues.  The
  default is \mvar{UTS\_RESET}. \\
  
  \pvar{script\_atomic}: &amp; When \var{true}, a started script will 
  complete if conditions suddenly fail. Legal values: true, false. The 
  default is false. \\
  
  \pvar{script\_name}: &amp; Unique (hopefully) name given to this script. 
  The default is \var{"unnamed"}. \\
  
  \pvar{shuffle}: &amp; If \var{true}, timestamps are recalculated on each
  reset of the script. Legal values: true, false. The default is
  \var{true}. Section \ref{sec_uts_reset}. \\
  
  \pvar{status\_var}: &amp; A MOOS variable for posting status summary. The
  default is \mvar{UTS\_STATUS}. Section \ref{sec_uts_status}\\
  
  \pvar{time\_warp}: &amp; Rate at which time is accelerated in executing the script.
  Legal values: any non-negative number. The default is zero. Section
  \ref{sec_uts_time_warp}. \\
  
  \pvar{time\_zero}: &amp; The base time upon which script event times are
  based.  The default is \var{"script\_start"}, the time at which
  \app{uTimerScript} is launched. The one alternative is
  \var{"db\_start"}, the time at which the MOOSDB was launched.  The
  default is \var{"script\_start"}. \\
  
  \pvar{upon\_awake}: &amp; Reset or re-start the script upon conditions
  being met after failure (\var{"n/a"}). Section \ref{sec_uts_reset}. \\
  
  \pvar{verbose}: &amp; If \var{true}, progress output is generated to the
  console (\var{true}). \\

\end{longtable}
\end{listing}
  
%===================================================================
\section{Publications and Subscriptions for uTimerScript}
%===================================================================
%\index{uTimerScript!Publications and Subscriptions}
%\index{Publications and Subscriptions!uTimerScript}
\label{sec_uts_interface}

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

%===================================================================
\subsection{Variables Published by uTimerScript}
\label{sec_uts_pubs}

The primary output of \app{uTimerScript} to the \app{MOOSDB} is the set of
configured events, but one other variable is published on each
iteration, and another upon purposeful exit with the
\pvar{event}\psvar{=quit} event configuration.

\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_uts_appcast}.

\item \mvar{EXITED\_NORMALLY}: A posting made when the script contains
  and executes a \pvar{event}\psvar{=quit} event, to let other
  applications know that the disconnection of \app{uTimerScript} is
  not a concern for alarm.

\item \mvar{UTS\_STATUS}: A status string of script progress. Section
  \ref{sec_uts_status}.
\end{packed_itemize}


%===================================================================
\subsection{Variables Subscribed for by uTimerScript}
\label{sec_uts_subs}

The \app{uTimerScript} application will subscribe for the following
four MOOS variables to provide optional control over the flow of the
script by the user or other MOOS processes:

\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{EXITED\_NORMALLY}: When \app{uTimerScript} receives its
  own posting, it is assumed that all outgoing posts needed to be made
  before quitting have been received by the \app{MOOSDB}. Upon this receipt
  \app{uTimerScript} will quit.  See Section \ref{sec_uts_quit}.

\item \mvar{UTS\_NEXT}: When received with the value
  \var{"next"}, the script will fast-forward in time to the next
  event. See Section \ref{sec_uts_jump}. 
  
\item \mvar{UTS\_RESET}: When received with the value of
  either \var{"true"} or \var{"reset"}, the timer script will be
  reset. See Section \ref{sec_uts_reset}. 
    
\item \mvar{UTS\_FORWARD}: When received with a numerical
  value greater than zero, the script will fast-forward by the
  indicated time. See Section \ref{sec_uts_jump}. 
  
\item \mvar{UTS\_PAUSE}: When received with the value of
  \var{"true"}, \var{"false"}, \var{"toggle"}, the script will change 
  its pause state correspondingly. See Section \ref{sec_uts_pause}. 
\end{packed_itemize}

\noindent
In addition to the above MOOS variables, \app{uTimerScript} will
subscribe for any variables involved in logic conditions, described in
Section \ref{sec_uts_logic}.

%===================================================================
\subsection{An Example MOOS Configuration Block}
%\index{uTimerScript!Example Config Block}
%\index{Example Config Block!uTimerScript}

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

\vspace{0.1in}
\begin{consoleverb}
 $ uTimerScript --example
\end{consoleverb}
\vspace{0.1in}

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

\vspace{0.25in}
\begin{listing}{Example configuration of the uTimerScript application}
\label{lst_uts_econfig}
\footnotesize
\begin{verbatim}
   1  =============================================================== 
   2  uTimerScript Example MOOS Configuration                           
   3  =============================================================== 
   4  Blue lines:     Default configuration                        
   5                                                                  
   6  ProcessConfig = uTimerScript                                    
   7  {                                                               
   8    AppTick   = 4                                                 
   9    CommsTick = 4                                                 
  10                                                                  
  11    // Logic condition that must be met for script to be unpaused 
  12    condition      = WIND_GUSTS = true                            
  13    // Seconds added to each event time, on each script pass      
  14    delay_reset    = 0                                            
  15    // Seconds added to each event time, on first pass only       
  16    delay_start    = 0                                            
  17    // Event(s) are the key components of the script              
  18    event          = var=SBR_RANGE_REQUEST, val="name=archie", time=25:35  
  19    // A MOOS variable for taking cues to forward time            
  20    forward_var    = UTS_FORWARD   // or other MOOS variable   
  21    // If true script is paused upon launch                       
  22    paused         = false    // or {true}                     
  23    // A MOOS variable for receiving pause state cues             
  24    pause_var      = UTS_PAUSE     // or other MOOS variable   
  25    // Declaration of random var macro expanded in event values   
  26    randvar        = varname=ANG, min=0, max=359, key=at_reset    
  27    // Maximum number of resets allowed                           
  28    reset_max      = nolimit  // or in range [0,inf)           
  29    // A point when the script is reset                           
  30    reset_time     = none     // or {all-posted} or range (0,inf) 
  31    // A MOOS variable for receiving reset cues                   
  32    reset_var      = UTS_RESET     // or other MOOS variable   
  33    // If true script will complete if conditions suddenly fail   
  34    script_atomic  = false    // or {true}                     
  35    // A hopefully unique name given to the script                
  36    script_name    = unnamed                                      
  37    // If true timestamps are recalculated on each script reset   
  38    shuffle        = true                                         
  39    // If true progress is generated to the console               
  40    verbose        = true     // or {false}                    
  41    // Reset or restart script upon conditions being met after failure 
  42    upon_awake     = n/a      // or {reset,resstart}           
  43    // A MOOS variable for posting the status summary             
  44    status_var     = UTS_STATUS    // or other MOOS variable   
  45    // Rate at which time is accelerated in execuing the script   
  46    time_warp      = 1                                            
  47  }                                                               
\end{verbatim}
\end{listing}
\normalsize
 
%===================================================================
\section{Examples}
%===================================================================

The examples in this section demonstrate the constructs thus far
described for the \app{uTimerScript} application. In each case, the
use of the script obviated the need for developing and maintaining a
separate dedicated MOOS application.

%===================================================================
\subsection{A Script for Generating 100 Random Numbers}
\label{uts_example_numgen}
%\index{uTimerScript!Generate 100 random numbers}

The below script will generate 100 postings with random numbers
preceded by an initial "start" posting, and followed by an "end"
posting.

\vspace{0.1in}
\begin{listing}{A uTimerScript configuration for generating 100 random numbers}
\label{uts_script_randnums}
\footnotesize
\begin{verbatim}
//------------------------------------------
ProcessConfig = uTimerScript                                    
{                                                               
  rand_var    = varname=RND_VAL, min=0, max=50, key=at_post

  event = var=REPORT, val="start", time=0
  event = var=REPORT, val="accidents=$[RND_VAL], unique_id=$[TCOUNT]", time=0, amt=100
  event = var=REPORT, val="end", time=0
}                                                 
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
The above may result in postings like those below (take from an alog file):

\footnotesize
\begin{verbatim}
8.817     REPORT         uTimerScript    start 
8.817     REPORT         uTimerScript    accidents=35.234,unique_id=1 
8.817     REPORT         uTimerScript    accidents=32.01,unique_id=2 
8.818     REPORT         uTimerScript    accidents=26.982,unique_id=3 
...
8.856     REPORT         uTimerScript    accidents=32.3,unique_id=95 
8.857     REPORT         uTimerScript    accidents=13.324,unique_id=96 
8.857     REPORT         uTimerScript    accidents=27.624,unique_id=97 
8.858     REPORT         uTimerScript    accidents=28.901,unique_id=98 
8.858     REPORT         uTimerScript    accidents=18.9,unique_id=99 
8.859     REPORT         uTimerScript    accidents=35.72,unique_id=100 
8.859     REPORT         uTimerScript    end 
\end{verbatim}
\normalsize

\vspace{0.1in}
\noindent
To make the numerical values integers, use the \var{snap=1} option (available in the next release 
after 19.8). Using \var{snap=0.1} will round to the nearest tenth and so on. For example:


\vspace{0.1in}
\begin{verbatim}
  rand_var    = varname=RND_VAL, min=0, max=50, key=at_post, snap=1
\end{verbatim}


%===================================================================
\subsection{A Script Used as Proxy for an On-Board GPS Unit}
\label{uts_example_gps}
%\index{GPS}
%\index{uTimerScript!Simulated GPS Unit}

Typical operation of an underwater vehicle includes the periodic
surfacing to obtain a GPS fix to correct navigation error accumulated
while under water. A GPS unit that has been out of satellite
communication for some period normally takes some time to re-acquire
enough satellites to resume providing position information. From the
perspective of the helm and configuring an autonomy mission, it is 
typical to remain at the surface only long enough to obtain the 
GPS fix, and then resume other aspects of the mission at-depth.

\vspace{0.1in}
\noindent
Consider a situation as shown in Figure \ref{fig_uts_gps}, where the
autonomy system is running in the payload on a payload computer,
receiving not only updated navigation positions (in the form of
\mvar{NAV\_DEPTH}, \mvar{NAV\_X}, and \mvar{NAV\_Y}), but also a
"heartbeat" signal each time a new GPS position has been received
(\mvar{GPS\_RECEIVED}). This heartbeat signal may be enough to indicate
to the helm and mission configuration that the objective of the
surface excursion has been achieved.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.78\textwidth]{figures/uts_gps.png}
  \caption{{\bf Simulating a GPS Acknowledgment:} In a physical
    operation of the vehicle, the navigation solution and a
    \mvvar{GPS\_UPDATE\_RECEIVED} heartbeat are received from the main
    vehicle (front-seat) computer via a MOOS module acting as an
    interface to the front-seat computer. In simulation, the
    navigation solution is provided by the simulator without any
    \mvvar{GPS\_UPDATE\_RECEIVED} heartbeat. This element of
    simulation may be provided with uTimerScript configured to post
    the heartbeat, conditioned on the \mvvar{NAV\_DEPTH} information
    and a user-specified start delay to simulate GPS acquisition
    delay. }
\label{fig_uts_gps}
\end{figure}
\vspace{0.1in}

\noindent
In simulation, however, the simulator only produces a steady stream of
navigation updates with no regard to a simulated GPS unit. At this
point there are three choices: (a) modify the simulator to fake GPS
heartbeats and satellite delay, (b) write a separate simple MOOS
application to do the same simulation.  The drawback of the former is
that one may not want to branch a new version of the simulator, or
even introduce this new complexity to the simulator. The drawback of
the latter is that, if one wants to propagate this functionality to
other users, this requires distribution and version control of a new
MOOS application.

\vspace{0.1in}
\noindent
A third and perhaps preferable option (c) is to write a short script
for \app{uTimerScript} simulating the desired GPS
characteristics. This achieves the objectives without modifying or
introducing new source code. The below script in Listing
\ref{uts_script_gps} gets the job done.

\vspace{0.26in}

\begin{listing}{A uTimerScript configuration for simulating aspects of a GPS unit}
\label{uts_script_gps}
\footnotesize
\begin{verbatim}
  1  //------------------------------------------------------------
  2  // uTimerScript configuration block
  3  
  4  ProcessConfig = uTimerScript
  5  {
  6    AppTick   = 4
  7    CommsTick = 4
  8  
  9    paused      = false
 10    reset_max   = unlimited
 11    reset_time  = end
 12    condition   = NAV_DEPTH &lt; 0.2
 13    upon_awake  = restart
 14    delay_start = 20:120
 15    script_name = GPS_SCRIPT
 16
 17    event  = var=GPS_UPDATE_RECEIVED, val="RCVD_$[COUNT]", time=0:1
 18  }
\end{verbatim}
\end{listing}
\normalsize

%\index{uTimerScript!Resetting}
%\index{uTimerScript!Start Delay}
%\index{uTimerScript!Macros}

\vspace{0.20in} 

\noindent
This script posts a \mvar{GPS\_UPDATE\_RECEIVED} heartbeat message
roughly once every second, based on the event time \var{"time=0:1"} on
line 17. The value of this message will be unique on each posting due
to the \psvar{\$[COUNT]} macro in the value component. See Section
\ref{uts_macros_builtin} for more on macros. The script is configured
to restart each time it awakes (line 13), defined by meeting the
condition of (\var{NAV\_DEPTH &lt; 0.2}) which is a proxy for the vehicle
being at the surface. The \pvar{delay\_start} simulates the time
needed for the GPS unit to reacquire satellite signals and is
configured to be somewhere in the range of 20 to 120 seconds (line
14). Once the script gets past the start delay, the script is a single
event (line 17) that repeats indefinitely since \pvar{reset\_max} is
set to \var{unlimited} and \pvar{reset\_time} is set to \var{end} in
lines 10 and 11. This script is used in the IvP Helm example
simulation mission labeled \var{"s4\_delta"} illustrating the
PeriodicSurface helm behavior.

%===================================================================
\subsection{A Script as a Proxy for Simulating Random Wind Gusts}
\label{uts_example_wind}
%\index{Wind}
%\index{uTimerScript!Simulated Random Wind Gusts}

Simulating wind gusts, or in general, somewhat random external
periodic drift effects on a vehicle, are useful for testing the
robustness of certain autonomy algorithms. Often they don't need to be
grounded in very realistic models of the environment to be useful, and
here we show how a script can be used simulate such drift effects in
conjunction with the uSimMarine application.

\vspace{0.1in}
\noindent
The \app{uSimMarine} application is a simple simulator that produces a
stream of navigation information, \mvar{NAV\_X}, \mvar{NAV\_Y},
\mvar{NAV\_SPEED}, \mvar{NAV\_DEPTH}, and \mvar{NAV\_HEADING} (Figure
\ref{fig_uts_wind}), based on the vehicle's last known position and
trajectory, and currently observed values for actuator variables. The
simulator also stores local state variables reflecting the current
external drift in the x-y plane, by default zero. An external drift
may be specified in terms of a drift vector, in absolute terms with
the variable \mvar{USM\_DRIFT\_VECTOR}, or in relative terms with the
variables \mvar{USM\_DRIFT\_VECTOR\_ADD}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.78\textwidth]{figures/uts_wind.png}
  \caption{{\bf Simulated Wind Gusts:} The \vvar{uTimerScript}
    application may be configured to post periodic sequences of
    external drift values, used by the uSimMarine application to
    simulate wind gust effects on its simulated vehicle.}
\label{fig_uts_wind}
\end{figure}
\vspace{0.1in}

\noindent
The script in Listing \ref{uts_script_wind} makes use of the
uSimMarine interface by posting periodic drift vectors. It simulates a
wind gust with a sequence of five posts to increase a drift vector
(lines 18-22), and complementary sequence of five posts to decrease
the drift vector (lines 24-28) for a net drift of zero at the end of
each script execution.

\vspace{0.25in}

\begin{listing}{A uTimerScript configuration for simulating simple wind gusts}
\label{uts_script_wind}
\footnotesize
\begin{verbatim}
  1  //------------------------------------------
  2  // uTimerScript configuration  block
  3   
  4  ProcessConfig = uTimerScript
  5  {
  6    AppTick   = 2
  7    CommsTick = 2
  8 
  9    paused        = false
 10    reset_max     = unlimited
 11    reset_time    = end
 12    delay_reset   = 10:60
 13    time_warp     = 0.25:2.0
 14    script_name   = WIND
 15    script_atomic = true
 16  
 17    randvar = varname=ANG, min=0,   max=359, key=at_reset
 18    randvar = varname=MAG, min=0.5, max=1.5, key=at_reset
 19    
 20  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*0.2}", time=0
 21  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*0.2}", time=2
 22  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*0.2}", time=4
 23  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*0.2}", time=6
 24  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*0.2}", time=8
 25
 26  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*-0.2}", time=10
 27  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*-0.2}", time=12
 28  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*-0.2}", time=14
 29  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*-0.2}", time=16
 30  event = var=DRIFT_VECTOR_ADD, val="$(ANG),{$(MAG)*-0.2}", Time=18
 31  }
\end{verbatim}
\end{listing}
\normalsize
%\index{uTimerScript!Resetting}
%\index{uTimerScript!Start Delay}
%\index{uTimerScript!Macros}

\vspace{0.25in} 
\noindent
The drift {\em angle} is chosen randomly in the range of $[0,359]$ by
use of the random variable macro \psvar{\$[ANG]} defined on line 
16. The peak {\em magnitude} of the drift vector is chosen randomly in
the range of $[0.5, 1.5]$ with the random variable macro \psvar{\$[MAG]}
defined on line 17. Note that these two macros have their random
values reset each time the script begins, by using the
\var{key=at\_reset} option, to ensure a stream of wind gusts of
varying angles and magnitudes.

\vspace{0.1in}
\noindent
*The duration of each gust sequence also varies between each script
execution. The default duration is about 20 seconds, given the
timestamps of 0 to 18 seconds in lines 19-29. The \pvar{time\_warp}
option on line 12 affects the duration with a random value chosen from
the interval of $[0.25, 2.0]$. A time warp of $0.25$ results in a gust
sequence lasting about 80 seconds, and $2.0$ results in a gust of
about 10 seconds. The time between gust sequences is chosen randomly
in the interval $[10, 60]$ by use of the \pvar{delay\_restart}
parameter on line 11. Used in conjunction with the \pvar{time\_warp}
parameter, the interval for possible observed delays between gusts is
$[5, 240]$. The \pvar{reset\_time} parameter set to \var{end}, on line
10 is used to ensure that the script posts all drift vectors to avoid
any accumulated drifts over time. The \pvar{reset\_max} parameter is
set to \var{"unlimited"} to ensure the script runs indefinitely.

\end{document}

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