<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{iGPSSim: A GPS Simulator}
\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, CSAIL}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=PavLab.IGPSSim}
\wikidoc{bugz=iGPSSim}
\wikidoc{auth=ayaari@mit.edu}


%====================================================================
\section{iGPSSim: A GPS Simulator}
%====================================================================
\label{sec_using_simg}

The \app{iGPSSim} application is a GPS simulator that streams data to
an actual or virtual serial port. Typically, \app{uSimMarine}
publishes the \mvar{NAV\_*} variables for a simulated vehicle. By
streaming to a serial port, \app{iGPSSim} forces the inclusion of a
GPS module such as \app{iGPSDevice} to parse the stream and publish
the \mvar{NAV\_*} variables.

The first benefit of running \app{iGPSSim} is the ability to test (or
unit test) the GPS application, whether crafting a new driver or
running \app{iGPSDevice}. The second benefit is to maintain a common
mission file for simulated and vehicle deployment. With a serial GPS
simulator in place, \app{iGPSDevice} remains constant between
simulations and field deployments.

%====================================================================
\subsection{Simluated Serial Ports with socat}
\label{subsec_socat}

The command-line application \var{socat} is a versatile tool for
working with data streams. Its main purpose is to establish, connect,
and transfer data between two streams. The \var{socat} program can
create two virtual serial ports called pseudo-ttys (PTY) that act as
direct replacements for physical serial ports. The first PTY is used
by the GPS simulator to stream into. The GPS module (e.g.,
\app{iGPSDevice}) attaches to the second PTY. \var{socat} ties them
together with a full-duplex connection.

When \var{socat} is launched, it creates the two PTY connections in
the \var{/dev/} directory, named incrementally based from existing
PTYs. Since the connection name may vary each time, \var{socat} is
instructed to also create a symbolic link to the PTYs it creates. MOOS
apps connecting to the virtual serial ports use the link names, which
are always consistent.

\paragraph{Acquiring and Installing socat.} {\em Version 1.7.3 of \var{socat} 
is required due to enhancements to "raw" data mode on serial connections.}
On Ubuntu systems, \var{socat} can be installed with \var{sudo apt-get
  install socat}. On OS X systems, MacPort can be used, \var{sudo port
  install socat}. On all systems, \var{socat} can be built from
source, acquired from the developer's website:
{http://www.dest-unreach.org/socat}.

\paragraph{Launching socat.} When launched, \app{iGPSSim} and \app{iGPSDevice} 
will attempt to connect the ports as defined in their respective
mission file blocks. Therefore, it is necessary to launch \var{socat}
{\em before} launching the MOOS mission. This can be done manually or
automated by including a \var{launch.sh} script instruction before the
\app{pAntler} line.

The following launches \var{socat}, which creates two PTY connections:

\vspace{0.1in}
\begin{consoleverb}
$ socat -d -d pty,rawer,link=./GPSSIM pty,rawer,link=./GPSDEVICE &amp;
\end{consoleverb}
\vspace{0.05in}

\begin{packed_itemize}[2]
	
\item \mvar{-d -d}: Command-line option to print fatal, error, warning, and 
  notice messages to the console.
  
\item \mvar{pty,rawer,link=./GPSSIM}: Parameter grouping that defines 
  the first PTY.
  
\item \mvar{pty,rawer,link=./GPSDEVICE}: Parameter grouping that describes 
  the second PTY.
  
\item \mvar{\&amp;}: Command-line directive that forces socat to run 
  asynchronously in the background. Console output will still broadcast to 
  the terminal it was launched in.
  
\item \mvar{pty}: Indicates that the grouping is defining a PTY.
  
\item \mvar{rawer}: Input and output are effectively unmodified when
  traveling through the PTY. When using rawer, echo is automatically
  turned off.
	
\item \mvar{link}: Path to a symbolic link that will be created for
  the PTY. Any existing file with the same name will be overwritten;
  an invalid path will force an error. The name provided here can be
  used as the mission file parameter for the serial port.
	
\end{packed_itemize}


\paragraph{Adding socat to the launch script.} Listing \ref{lst_launch_script} 
shows an example of how to launch \var{socat} automatically from within a 
launch script. Line 5 includes the command:

\vspace{0.25in}
\begin{listing}{Portion of sample launch script showing how to start socat on 
line 5}
\label{lst_launch_script}
\footnotesize
\begin{verbatim}
1   #  Part 3: Launch the processes
2   #-------------------------------------------------------
3   
4   # Launch socat to create pseudo tty
5   socat -d -d pty,rawer,link=./GPSSIM pty,rawer,link=./GPSDEVICE &amp;
6   
7   printf "Launching $VNAME1 MOOS Community (WARP=%s) \n" $TIME_WARP
8   pAntler targ_$VNAME1.moos &gt;&amp; /dev/null &amp;
9   sleep .25
10  printf "Launching $SNAME MOOS Community (WARP=%s) \n"  $TIME_WARP
11  pAntler targ_shoreside.moos &gt;&amp; /dev/null &amp;
12  printf "Done \n"
13  
14  uMAC targ_simHab.moos
15  
16  printf "Killing all processes ... \n"
17  mykill
18  kill %1 %2 %3 %4 %5
19  printf "Done killing processes.   \n"
\end{verbatim}
\normalsize
\end{listing}

%====================================================================
\subsection{Sample Launch Scenario}
%====================================================================

One use of \app{iGPSSim} is to provide source data for unit testing a
GPS module (\app{iGPSDevice} will be used in this example). The
scenario is the basic alpha mission where \app{uSimMarine} is
simulating the vehicle position.  Usually, \var{NAV\_*} variables
would source directly from \app{uSimMarine}.  However, for testing,
the GPS application must be configured to publish these.

There are two main steps to modify a mission for emulated GPS. First,
alter the launch script to start \app{socat} as per the instructions
in Section \ref{sec_using_simg}. Second, change the \var{.moos}
file as follows:

\vspace{0.15in}
\begin{listing}{Modifications to launch script to include emulated GPS}
  \label{lst_simGPS_mods}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.76\textwidth}} 
    
    \app{uSimMarine} &amp; Change the \pvar{prefix} parameter to \pvar{SIM} \\
    
    \app{iGPSSim}: &amp; Add a new ProcessConfig block by copying the sample 
    config from Listing \ref{lst_simg_econfig}. \\
    
    \app{iGPSSim}: &amp; Modify the \pvar{port} parameter to \pvar{./GPSSIM}; 
    change \pvar{PASHR} parameter to \pvar{true}. \\
    
    \app{iGPSDevice}: &amp; Add a new ProcessConfig block with the following 
    contents:

  \end{longtable}
\end{listing}
    
\vspace{0.25in}

\noindent
For \app{iGPSDevice}, the configuraiton block should look like:

\begin{fileverb}
  ProcessConfig = iGPSDevice
   {
     AppTick   = 10
     CommsTick = 10

     Port      = ./GPSDEVICE
     BaudRate  = 19200
     Prefix    = NAV_

     Heading_Source = PASHR
     Trigger_Msg    = gpgga
   }
\end{fileverb}

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

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for iGPSSim}
\label{lst_simg_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 
	
  \pvar{port}: &amp; Fully-qualified path to the operating system serial device 
  (can be an existing pseudo-tty or an actual serial port) \\
  
  \pvar{baudrate}: &amp; One of 2400, 4800, 9600, 19200, 38400, 56700, or 114200 
  \\
  
  \pvar{input\_prefix}: &amp; Prefix that is prepended to the subscription names. 
  Underscore is added if not included. \\
  
  \pvar{gpgga}: &amp; \pvar{TRUE} or \pvar{FALSE}, publish GPGGA message (default 
  = \pvar{true}) \\
  
  \pvar{gphdt}: &amp; \pvar{TRUE} or \pvar{FALSE}, publish GPHDT message (default 
  = \pvar{false}) \\
  
  \pvar{gprmc}: &amp; \pvar{TRUE} or \pvar{FALSE}, publish GPRMC message (default 
  = \pvar{true}) \\
  
  \pvar{gptxt}: &amp; \pvar{TRUE} or \pvar{FALSE}, publish GPTXT message (default 
  = \pvar{false}) \\
  
  \pvar{pashr}: &amp; \pvar{TRUE} or \pvar{FALSE}, publish PASHR message (default 
  = \pvar{false}) \\
  
\end{longtable}
\end{listing}


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

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

\vspace{0.1in}
\begin{consoleverb}
$ iGPSSim --example or -e
\end{consoleverb}
\vspace{0.1in}
	
\vspace{0.25in}
\begin{listing}{Example configuration of the iGPSSim application}
\label{lst_simg_econfig}
\footnotesize
\begin{verbatim}
1   ============================================================================
2   iGPSSim Example MOOS Configuration
3   ============================================================================
4
5   ProcessConfig = iGPSSim
6   {
7       AppTick    = 5               // Ticks should be set to the frequency of
8       CommsTick  = 5               //   the GPS being simulated
9       Port         = /dev/ttyACM1  // Fully-qualified path to the serial port
10      BaudRate        = 19200      // Serial port baud rate
11      INPUT_PREFIX    = SIM_       // Prefix for input _HEADING, _SPEED, etc.
12      GPGGA           = true       // Publish GPGGA? (default: true)
13      GPHDT           = false      // Publish GPHDT? (default: false)
14      GPRMC           = true       // Publish GPRMC? (default: true)
15      GPTXT           = false      // Publish GPTXT? (default: false)
16      PASHR           = false      // Publish PASHR? (default: false)
17   }
\end{verbatim}
\normalsize
\end{listing}

%==================================================================
\section{Publications and Subscriptions for iGPSSim}
%==================================================================
%\index{iGPSSim!Publications and Subscriptions}
%\index{Publications and Subscriptions!iGPSSim}
\label{sec_simg_interface}

The interface for \app{iGPSSim}, 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}
$ iGPSSim --interface or -i
\end{consoleverb}
\vspace{0.05in}
                             
%==================================================================
\subsection{Variables Published by iGPSSim}
\label{sec_simg_pubs}

\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.
	
\end{packed_itemize}

%==================================================================
\subsection{Variables Subscribed for by iGPSSim}
\label{sec_simg_subs}

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

\begin{packed_itemize}[2]
	
\item \mvar{[prefix]\_X}: Current X position on the local grid as reported 
  by a simulated source.
  
\item \mvar{[prefix]\_Y}: Current Y position on the local grid as reported 
  by a simulated source.
  
\item \mvar{[prefix]\_SPEED}: Current vehicle speed as reported by a 
  simulated source.
  
\item \mvar{[prefix]\_HEADING}: Current vehicle heading as reported by a 
  simulated source.
  
\end{packed_itemize}

\end{document}

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