<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{The pMapValues Application}
\vspace{0.1in}
\labdate{Fall 2017}
\vspace{0.1in}
\labauth{Alon Yaari, ayaari@mit.edu}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PMapValues}
\wikidoc{bugz=pMapValues}
\wikidoc{auth=ayaari@mit.edu}


%====================================================================
\section{Overview}
%====================================================================
\label{sec_pMapValues}
\index{pMapValues}

The main purpose of the \app{pMapValues} application is to convert an
input value to a defined mapping in an output range. The secondary
purpose is to trigger based on an input condition. This application
was originally created to convert joystick axis values published from
\app{iJoystick} into \var{DESIRED\_THRUST} and \var{DESIRED\_RUDDER}
messages. The application handles trigger messages, where values are
published based on a conditional input such as button presses or
releases. Both the range and trigger features can be extended to any
non-joystick message inputs.

%====================================================================
\section{Mapping Range Values}
\label{subsec_mappingRanges}

Per a mission file definition, a MOOS message provides a regularly
updated data stream. Inputs values are expected to fall within some
range, for a joystick axis message the input range is $[-32768,
  32768]$. If for example the user wished to map an axis to
\var{DESIRED\_RUDDER} values, \app{pMapValues} can be configured to
map to an output of $[-40, 40]$.

\paragraph{Data constraints.} 
Input values are defined in the mission file with an expected range,
more specifically the maximum and minimum values that are anticipated
for the stated input message. If an input data element arrives outside
of that range, it is constrained into the valid range. For example, if
the input range is defined as $[0, 100]$, a value of $105$ would be
constrained to the value $100$.

\paragraph{Joystick dead zones and saturation.} 
Self-centering controllers return to the general middle, reporting a
position somewhere around zero. The mission file parameter
\pvar{dead\_zone} is a percentage of the range from center that when
within the zone corresponds to a zero value. For example if
\psvar{dead\_zone=5}, then any position within $[-1638, 1638]$
(5\% of $32767$) reports a value of $0$.

Pushing the stick to extreme minimum or maximum does not always report
full value. The mission file parameter \pvar{saturation} is a
percentage of travel from the axis ends that report full value
(saturation). For example, if \psvar{saturation=5}, then any position
reporting less than $-31129$ or greater than $31129$ (95\% of $32767$)
translates to full negative or positive value.

In Figure \ref{fig_joystickAxis}, the input value \var{JOY0\_AXIS1} is
published by \app{iJoystick}. The \app{pMapValues} mission file has a
\psvar{range} definition:

\vspace{0.1in}
\begin{consoleverb}
  range = in_msg=JOY0_AXIS1, in_min=-32768, in_max=32768, in_dead=10, in_sat=5, \
          out_msg=DESIRED_RUDDER, out_min=-40, out_max=40
\end{consoleverb}

\vspace{0.1in}
\noindent
that maps the joystick axis to valid rudder angles. Note the dead zone
(green region $[-3277, 3277]$) and saturation areas (blue regions at
the ends) of the input range.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/joystickAxis.png}
\caption{Mapping from raw joystick axis to rudder angles, taking into
  account dead zone and saturation}
\label{fig_joystickAxis}
\end{figure}
\vspace{0.1in}

\noindent
Axis position between the dead zone and saturated end are normalized
for the remaining continuous range.

%====================================================================
\section{Dependent Axes}

On most joystick controllers, a single stick will have two axes, a
vertical and a horizontal.  In some cases, these are independent,
meaning the position of the X-axis has no relation to the reading from
the Y-axis and vice versa. Typically, manually moving the stick around
its extent will reveal a square pattern.

In some (mostly gaming) joysticks (e.g., the XBox 360 Controller),
axes sharing the same stick are dependent. Movement is restricted to a
circular physical limit and the corresponding values will report
maximums related to the definition of a circle. When pushing the stick
fully downward, axis values report \var{axis\_0=0.0} and \var{axis\_1=1.0}. 
Similarly, fully rightward results in \var{axis\_0=1.0} and
\var{axis\_1=0.0}. However, setting the stick fully to the bottom-right
results in \var{axis\_0=0.7} and \var{axis\_1=0.7}, the axes at their full
extents transcribe the definition of a circle and values cannot reach
$1.0$ unless the dependent axis is at $0.0$.

General input messages contain a single numerical value, such as when
\app{iJoystick} reports raw axis position. Dependent axes are
published as a string-type MOOS message with a \msvar{\_DEP}
suffix. Content is a pair of comma-separated values in a string
arranged as \var{AXIS\_VAL, DEPENDENT\_AXIS\_VAL}. \app{pMapValues}
recognizes that the input is a pair of dependent axes and adjusts
calculations accordingly. It is expected that both inputs follow the
same range definitions.

%====================================================================
\section{Switch Triggering}
\label{subsec_switchTriggers}

The \app{iJoystick} application publishes \var{DOWN} when a button is
pressed and \var{UP} when released. These are trigger values, being
published only when the button status changes. \app{pMapValues} can be
configured to trigger new publications on these triggers. For example,
a user wishes to have a joystick available for manual control of a
vessel when operating near a mooring field. Axis values are mapped to
\mvar{DESIRED\_RUDDER} and \mvar{DESIRED\_THRUST}. To enact the control,
\app{pMapValues} is configured to publish
\mvar{MOOS\_MANUAL\_OVERIDE=true} on receipt of
\mvar{JOY0\_BUTTON\_0==DOWN} and \var{false} when
\mvar{JOY0\_BUTTON\_0==UP}.

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

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for pMapValues}
  \label{lst_phi_params}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.76\textwidth}} 
    
    \pvar{range}: &amp; (string) \var{key=value} pairs defining the range
    mapping of input and output messages. See Section
    \ref{subsubsec_rangeParam} below.\\
    
    \pvar{depends}: &amp; String defining a pair of dependent axes. The
    parameter expects two comma-separated names that are defined as
    \var{in\_msg} in \var{range} definitions. Order is unimportant. \\

    \pvar{trigger}: &amp; (string) \var{key=value} pairs defining an input
    message that triggers the publication of a defined output
    message. The trigger value can be string or numeric. Quotes around
    a number will cause it to be treated as a string. See Section
    \ref{subsubsec_triggerParam} below. \\
    
  \end{longtable}
\end{listing}

%---------------------------------------------------------------
\subsection{pMapValues Range Parameter}
\label{subsubsec_rangeParam} 

\begin{tabular}{|l|l|l|l|l|} \hline
  {\bf Key} &amp; {\bf Type} &amp; {\bf Required} &amp; {\bf Example} &amp; {\bf Description} \\ \hline
  \var{in\_msg} &amp; string &amp; yes &amp; \var{in\_msg}var{=JOY0\_AXIS0} &amp; Name of the message for the incoming numerical data. \\ \hline
  \var{in\_min} &amp; double &amp; yes &amp; \var{in\_min}var{=-32768} &amp; Minimum value expected on the input range. \\ \hline
  \var{in\_max} &amp; double &amp; yes &amp; \var{in\_max}var{=32768} &amp; Maximum value expected on the input range. \\ \hline
  \var{in\_dead} &amp; double &amp; no &amp; \var{in\_dead}var{=5} &amp; (Dead zone) Percent of range away from zero that maps to an output of zero. \\ \hline
  \var{in\_sat}  &amp; double &amp; no &amp; \var{in\_sat}=var{=7} &amp; (Saturation) Percent of range away from each end that maps to an output of min or max. \\ \hline
  \var{out\_msg}  &amp; string &amp; yes &amp; \var{out\_msg}var{=DESIRED\_RUDDER} &amp; Name of the output message for publishing mapped values. \\ \hline
  \var{out\_min}  &amp; double &amp; yes &amp; \var{out\_min}var{=-40} &amp; Minimum value to map output. \\ \hline
  \var{out\_max}  &amp; double &amp; yes &amp; \var{out\_max}var{=40} &amp; Maximum value to map output. \\ \hline
\end{tabular}

%--------------------------------------------------------------
\subsection{pMapValues Trigger Parameter}
\label{subsubsec_triggerParam}
\vspace{0.15in}
\begin{listing}{Elements of the Trigger parameter for pMapValues}
  \label{lst_trigger_params}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.76\textwidth}} 
    
    \msvar{in\_msg}: &amp; (string, required) Message name to be monitored
    for the trigger. Example: \var{in\_msg=JOY0\_BUTTON0} \\
		
    \msvar{trigger}: &amp; (string or numeric, required) Trigger when the
    \msvar{in\_msg} message changes to this value. Valid values are
    any string, number, or number in quotes (to denote a
    string. Example: \var{trigger=down} \\
		
    \msvar{out\_msg}: &amp; (string, required) Message name for the
    publication when triggered. Example: \var{out\_msg=DEPLOY} \\
		
    \msvar{out\_val}: &amp; (string or numeric, required) Value that is
    published in the \msvar{out\_msg} message when triggered. Valid
    values are any string, number, or number in quotes (to denote a
    string. Example: \var{out\_val=true} \\
		
  \end{longtable}
\end{listing}

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

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

\vspace{0.1in}
\begin{consoleverb}
$ pMapValues --example or -e
\end{consoleverb}
\vspace{0.1in}
	
\vspace{0.25in}
\begin{listing}{Example configuration of the pMapValues application}
\label{lst_pMapValues_econfig}
\footnotesize
\begin{verbatim}
1   ============================================================================
2   pMapValues Example MOOS Configuration
3   ============================================================================
4   
5   ProcessConfig = pMapValues
6   {
7       AppTick    = 10
8       CommsTick  = 10
9
10  // RANGE = in_msg=, in_min=, in_max=, dead=, sat=, norm_min=, norm_max=, /
11  //         out_msg=, out_min=, out_max=, dep=
12  //      in_msg  (string, required)  Message name for incoming range values
13  //      in_min  (double, required)  Minimum expected value on the input message
14  //      in_max  (double, required)  Maximum expected value on the input message
15  //      norm_min (double, optional) Minimum normalized value to map to output (default = -1.0)
16  //      norm_max (double, optional) Maximum normalized value to map to output (default = 1.0)
17  //      out_msg (string, required)  Mapped value published to this message
18  //      out_min (double, required)  Minimum value input range is mapped to
19  //      out_max (double, required)  Maximum value input range is mapped to
20  //      dead    (int,    optional)  Percent to each side of 0 that reports 0
21  //      sat     (int,    optional)  Percent at each end that reports extreme value
22  //                                    Use single-value input for any other
23  //                                    value or if omitted.
24  RANGE = in_msg=JOY_AXIS_0, in_min=-32768, in_max=32768, dead=5, sat=5, /
25          out_msg=DESIRED_RUDDER, out_min=-40, out_max=40
26  RANGE = in_msg=JOY_AXIS_1_DEP, in_min=-32768, in_max=32768, dead=5, sat=5, /
27          norm_min = 0.0, norm_max = -1.0, out_msg=DESIRED_THRUST, out_min=0, out_max=100
28  
29  // TRIGGER = in_msg=w, in_val=x, out_msg=y, out_val=z
30  //      in_msg  (string, required) Message name for incoming switch value
31  //      trigger (any,    required) When in_msg contents change to match this trigger,
32  //                                   the out_msg will be published. String/numeric agnostic.
33  //      out_msg (string, required) Message name for resulting publication.
34  //      out_val (any,    required) Resulting publication posts this value.
35  //                                   If value is a numeric (within '+-.01234567889'),
36  //                                   published message is a double. Otherwise, a
37  //                                   string is published. To publish a numeric as a
38  //                                   string, put the number in quotes.
39  TRIGGER   = JOY_BUTTON_4, 1, ALL_STOP=true
40  TRIGGER   = JOY_BUTTON_7, off, VEHICLE_NUMBER="3"
41  }                         
\end{verbatim}
\normalsize
\end{listing}

%=============================================================
\section{Publications and Subscriptions for pMapValues}
\index{pMapValues!Publications and Subscriptions}
\index{Publications and Subscriptions!pMapValues}
\label{sec_pMapValues_interface}

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

%---------------------------------------------------------------------
\subsection{Variables Published by pMapValues}
\label{sec_pMapValues_pubs}

The primary output messages of \app{pMapValues} are mapped values,
triggered publications, and appcasting reports.

\begin{packed_itemize}[2]
  
\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Reports are posted only in response to an appcast
  request messages.
	
\item \mvar{range out\_msg}: (double) Value mapped from an input
  message, as defined in a \pvar{range} parameter in the mission file.
	
\item \mvar{trigger out\_msg}: (double or string) Value triggered by
  an input message condition, as defined in a \pvar{trigger} parameter
  in the mission file. Message type is determined by the type defined
  in the \pvar{trigger} parameter, see Section
  \ref{subsubsec_triggerParam}.
	
\end{packed_itemize}

%------------------------------------------------------------------
\subsection{Variables Subscribed for by pMapValues}
\label{sec_pMapValues_subs}

The \app{pMapValues} application only subscribes to appcasting
requests and has no other message inputs.

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


\end{document}

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