\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{pSpoofNode: Spoofing Node Reports for Non-Existing Vehicles}
\vspace{0.1in}
\labdate{January 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labsrc{project-pavlab/appdocs/app\_pspoofnode} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PSpoofNode}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
\section{Overview}
%===================================================================
\label{sec_psn}

\vspace{0.1in}
\noindent
{\bf Note:} This app added to MOOS-IvP after Release 24.8.

\vspace{0.1in}
\noindent
The \app{pSpoofNode} application is a tool for generating node report
messages, as if they were being generated by vessels running
\app{pNodeReporter}. By using this app, one or more node reports can
be generated for some set initial position, heading and speed, for
some duration, before they cease to be posted.  In this way,
applications like the helm and contact manager can be tested in a
number of high contact volume edge cases to ensure correct operations,
including memory management and CPU load. Typically this process is
run on the shoreside MOOS community.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.55\textwidth]{figures/pspoofnode.png}
  \caption{{\bf Typical pSpoofNode Topology:} Node reports are
    generated in the shoreside community, and they are routed to
    all connected vehicles typically through the \app{uFldNodeComms}
    application.}
\label{fig_psn_topology}
\end{figure}

%===================================================================
\section{Configuration Parameters for pSpoofNode}
%===================================================================
\label{sec_psn_params}

The \app{pSpoofNode} 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{pSpoofNode}.

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

  \pvar{default\_length}: & The default length of the vehicle in meters,
  if no vehicle length is specified in the spoof request. The default
  value is 5. \\

  \pvar{default\_vtype}: & The default vehicle type posted in the node
  report, if no vehicle type is specified in the spoof request. The
  default value is kayak. \\

  \pvar{default\_group}: & The default vehicle group posted in the
  node report, if no vehicle group is specified in the spoof
  request. The default value is the empty string, since the group
  field is optional in node reports. \\

  \pvar{default\_vsource}: & The default vehicle source posted in the
  node report, if no vehicle source, e.g, AIS or radar, is specified
  in the spoof request. The default value is the empty string, since
  the vsource field is optional in node reports. \\

  \pvar{default\_color}: & The default vehicle color posted in the
  node report, if no vehicle color is specified in the spoof
  request. The default value is purple. \\

  \pvar{default\_heading}: & The default vehicle heading posted in the
  node report, if no vehicle heading is specified in the spoof
  request. The default value is 45. \\

  \pvar{default\_spd}: & The default vehicle speed posted in the
  node report, if no vehicle speed is specified in the spoof
  request. The default value is 2. \\

  \pvar{default\_duration}: & The default duration, in seconds, for
  posting a series of node reports for a contact, if the duration is
  not specified in the spoof request. The default value is -1, meaning
  node report, if no vehicle speed is specified in the spoof
  there is unlimited duration. \\

  \pvar{refresh\_interval}: & A minimum interval between node report
  publications. In seconds. The default is 1. Another way to slow down
  publications is with the AppTick, but this will also slow down the
  processing of new spoof requests. \\

  \pvar{spoof}: & A spoof request comprised of the fields found in a
  node report. The request must contain the vehicle position. All
  other fields are optional, relying on default values if a field is
  not specified in the spoof request. If the \var{name} is not
  specified, an auto-generated name will be used, beginning with
  \var{"C"} followed by an index incremented with each spoof
  request. Note: a spoof request may also be made through an incoming
  posting to the MOOS variable \mvar{SPOOF}. \\

\end{longtable}
\end{listing}

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

An example MOOS configuration block may be obtained from the command line
with the following:

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

\vspace{0.25in}
\begin{listing}{Example configuration of the pSpoofNode application}
\label{lst_psn_econfig}
\footnotesize
\begin{verbatim}
 1  =============================================================== 
 2  pSpoofNode Example MOOS Configuration                           
 3  =============================================================== 
 4                                                                  
 5  ProcessConfig = pSpoofNode                                      
 6  {                                                               
 7    AppTick   = 4                                                 
 8    CommsTick = 4                                                 
 9                                                                  
10    refresh_interval = 1         // Secs, default = 1             
11    default_length = 5           // Meters, default = 5           
12    default_vtype =              // Shape, default = kayak        
13    default_group =              // Default = ""                
14    default_vsource =            // Default = ""                
15    default_color =              // Default = purple              
16                                                                  
17    default_hdg = 45             // Degrees, default=45           
18    default_spd = 2              // M/sec, default=0              
19    default_duration = 0         // Sec, default=0, never expire  
20  }
\end{verbatim}
\end{listing}
\normalsize
 
%===================================================================
\section{Publications and Subscriptions for pSpoofNode}
%===================================================================
\label{sec_psn_interface}

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

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

%===================================================================
\subsection{Variables Published by pSpoofNode}
\label{sec_psn_pubs}

\begin{packed_itemize}[2]

\item \mvar{NODE\_REPORT}: A node report representing the spoofed
  node. 
  
\end{packed_itemize}
  
%===================================================================
\subsection{Variables Subscribed for by pSpoofNode}
\label{sec_psn_subs}

The \app{pSpoofNode} application subscribes to the following MOOS
variables:

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

\item \mvar{SPOOF\_CANCEL}: A request to cancel an ongoing spoofed node,
  based on vehicle name or group name.

\end{packed_itemize}

\vspace{0.1in}
\noindent
Example \mvar{SPOOF} requests:

\prevgreen
\begin{verbatim}
  SPOOF = x=12,y=9,hdg=180,spd=0.1,name=zed,group=blue_team,type=kayak,
          vsource=ais,len=5,color=green,dur=20 
  SPOOF = x=12,y=9,hdg=180,spd=0.4
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
Example \mvar{SPOOF\_CANCEL} requests:

\prevgreen
\begin{verbatim}
  SPOOF_CANCEL = vname=zed
  SPOOF_CANCEL = group=redteam
\end{verbatim}
\postverb

%===================================================================
\subsection{Command Line Usage of pSpoofNode}
\label{sec_psn_cmdline}

The \app{pSpoofNode} application is typically launched with pAntler,
along with a group of other modules. However, it may be launched
separately from the command line. The command line options may be
shown by typing:

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

\vspace{0.1in}
\begin{listing}{Command line usage for the pSpoofNode tool}
\label{psn_usage}
\footnotesize
\begin{verbatim}
  1  Usage: pSpoofNode file.moos [OPTIONS]             
  2                                                         
  3  Options:                                               
  4    --alias=<ProcessName>                                
  5        Launch pSpoofNode with the given process    
  6        name rather than pSpoofNode
  7    --example, -e                                        
  8        Display example MOOS configuration block         
  9    --help, -h                                           
 10        Display this help message.                       
 14    --interface, -i                                               
 15        Display MOOS publications and subscriptions.      
 16    --version,-v                                         
 17        Display the release version of pSpoofNode.
 18    --web,-w                                                      
 19        Open browser to: https://oceanai.mit.edu/ivpman/apps/pSpoofNode
 20 
 21  Note: If argv[2] is not of one of the above formats 
 22        this will be interpreted as a run alias. This 
 23        is to support pAntler launching conventions.  
\end{verbatim}
\end{listing}
\normalsize

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

Some useful information is published by \app{pSpoofNode} to the
terminal on every iteration. An example is shown in Listing
\ref{lst_psn_appcast} below. This application is also appcast enabled,
meaning its reports are published to the MOOSDB and viewable from any
uMAC application or \app{pMarineViewer}. The counter on the end of
line 2 is incremented on each iteration of \app{pSpoofNode}, and also
serves as a heartbeat indicator. The \var{"0/0"} also on line 2
indicates there are no configuration or run warnings detected.

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{pSpoofNode}}
\label{lst_psn_appcast}

\footnotesize
\begin{verbatim}
 1  ===================================================================
 2  pSpoofNode shoreside                                       0/0(228)
 3  ===================================================================
 4  Config:                                  
 5    Default Type:    kayak
 6    Default Color:   dodger_blue
 7    Default Group:   
 8    Default VSource: 
 9    refresh Interv:  1
10  
11  Postings: 36
12  
13  VName  XPos  YPos    Hdg  Spd  Age
14  -----  ----  ------  ---  ---  ----
15  ben    36.7  -107.9  0    0    12.1
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
Lines 4-7 of the output show the user configuration. Lines 13-15 show the
most recent spoof request per vehicle. The requested position, heading and
speed are shown. The Age column represents how long ago the spoof request
was generated.
\end{document}

