<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{uSimM200: Emulating the Kingfisher M200 USV}
\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=PavLab.USimM200}
\wikidoc{bugz=uSimM200}
\wikidoc{auth=ayaari@mit.edu}

%====================================================================
\section{uSimM200: Emulating the Kingfisher M200 USV}
%====================================================================
\label{sec_usim_m200}
\index{uSimM200}

\vspace{0.2in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.45\textwidth]{figures/M200architecture.png}
  \caption{The \app{uSimM200} application and actual hardware are 
    interchangeable; the only change on the vehicle mission between emulation 
    and deployment is the IP address where motor commands are sent.}
  \label{fig_M200_architecture}
\end{figure}

%====================================================================
\section{Using the uSimM200 Application}
%====================================================================
\label{subsec_using_usim_m200}

The \app{uSimM200} application serves as a digital surrogate to the
front seat computer of a Clearpath Robotics Kingfisher M200 unmanned
surface vehicle. The M200 interfaces over an Ethernet connection using
a defined wire protocol. To a connecting system, \app{uSimM200}
provides an emulated interface, appearing identically to actual
vehicle hardware.

\app{uSimM200} operates as part of a dedicated MOOS community that
exists entirely to support emulation. For the most basic
implementation, only \app{uSimMarine} is required to manage a
simulated dynamic vehicle. At its core, \app{uSimM200} ingests
incoming wire protocol thrust commands to publish
\mvar{DESIRED\_THRUST} and \mvar{DESIRED\_RUDDER} messages internally.
\app{uSimMarine} simulates vehicle motion and publishes continuously
updated \mvar{NAV\_*} messages. \app{uSimM200} converts these to
Clearpath wire protocol sentences and pushes them out the emulated
interface.

%===================================================================
\subsection{Ethernet Port}
\label{subsubsec_port}
The primary external interface to \app{uSimM200} is the Ethernet connection on 
the local computer network interface, defined with the mission file parameter 
\pvar{port\_number}. Any external application wishing to interface should 
connect to the port number at IP address of the computer running 
\app{uSimM200}; \pvar{localhost} can be used when connecting on the same 
machine.

Whatever the Ethernet address, M200 vehicles listen for connections on port 
29500. By default, \app{uSimM200} monitors the same port that can be changed 
via the mission file parameter \pvar{port}. This value should be kept at the 
default to avoid confusion when shifting between emulation and actual hardware. 
However, it is necessary to change the port when running more than one emulator 
on the same computer.

%===================================================================
\subsection{Payload Autonomy}

\label{subsubsec_payload_autonomy}
{\bf Payload autonomy} is a paradigm for controlling an autonomous
vehicle where the autonomy software operates from a dedicated and
removable back-seat computer. A separate front-seat system manages
vehicle control and low-level sensing. The back-seat computer connects
physically through a payload port (usually Ethernet, sometimes serial)
and logically using a wire protocol. The Pablo Box for the Kingfisher
M200 is an example of a payload autonomy system.  Documentation for
the Pablo System provides additional details.

The \app{uSimM200} application is an integral part of fielding M200 vehicles, 
especially with a Pablo unit. The mission can be developed using 
\app{uSimMarine} as an application within the mission. However, in preparation 
for deployment on actual hardware the mission will be modified to turn off the 
simulator and turn on the vehicle interface. At this point, the mission can be 
validated against the emulator without requiring access to the actual hardware.

%===================================================================
\subsection{Actuation Commands}

The Clearpath wire protocol describes three commands for actuating the
vehicle, \var{\$PYDIR}, \var{\$PYDEV}, and \var{\$PYDEP}. The
\app{iM200} application uses \$PYDIR exclusively for thrusting each
motor independently.

\noindent
Note that the checksum on all messages to \app{uSimM200} is optional.

\paragraph{\$PYDIR (Command Vehicle Motors):} Adjusts the percentage of thrust 
directly to each motor; the commanded value is passed unfiltered to the motor 
controller. While it is possible to spin motors in reverse, 100\% thrust on the 
actual M200 vehicle contributes little to backward motion. Therefore, 
\app{uSimM200} internally constrains reverse motion to 5\% thrust.

\vspace{0.25in}
\begin{listing}{Definition of \$PYDIR command}
\label{lst_pydir}
\footnotesize
\begin{verbatim}
	          &lt;1&gt;  [DesThrustPctL] Percent thrust to the portside motor
	               Valid values are -100.0 to 100.0
	               Stopped = 0; Forward motion is positive
	          &lt;2&gt;  [DesThrustPctR] Percent thrust to the starboard motor
	               Valid values are -100.0 to 100.0
	               Stopped = 0; Forward motion is positive
              &lt;hh&gt; Optional checksum
\end{verbatim}
\normalsize
\end{listing}

\noindent
For example, full forward thrust can be commanded with:

\vspace{0.1in}
\begin{consoleverb}
	$PYDIR, 100.0, 100.0*&lt;CR&gt;&lt;LF&gt;
\end{consoleverb}
\vspace{0.1in}

\paragraph{\$PYDEV (Command Vehicle Helm):} Desired heading and speed is passed 
to the front seat. There, percent thrust to each motor is calculated and 
commanded to acheive the 
requested heading/speed. 

Note that as of this writing the \$PYDEV command is not correctly implemented 
on the M200 vehicle. However, \app{uSimM200} will respond properly to actuate 
the simulated vehicle. It does so by passing the heading/speed values to the 
simulated 

\vspace{0.25in}
\begin{listing}{Definition of \$PYDEV command}
\label{lst_pydev}
\footnotesize
\begin{verbatim}
	     $PYDEV,&lt;1&gt;,&lt;2&gt;*hh&lt;CR&gt;&lt;LF&gt;
	          &lt;1&gt;  [DesHeading] Desired heading relative to true north
	               Valid values are 0.0 to 359.9
	          &lt;2&gt;  [DesSpeed] Desired speed over ground
	               Valid values are 0.0 and positive real numbers
	          &lt;hh&gt; Optional checksum
	          \end{verbatim}
	          \normalsize
	          \end{listing}
	          

\paragraph{\$PYDEP (Command Desired Thrust):} 

\vspace{0.25in}
\begin{listing}{Definition of \$PYDEP command}
\label{lst_pydep}
\footnotesize
\begin{verbatim}
	     $PYDEP,&lt;1&gt;,&lt;2&gt;*hh&lt;CR&gt;&lt;LF&gt;
	          &lt;1&gt;  [DesYawRate] Desired rate of yaw, in radians/sec
	          &lt;2&gt;  [DesThrustPct] Desired percent of thrust, -100 to 100
	               Stopped = 0; Forward motion is positive
	          &lt;hh&gt; Optional checksum
\end{verbatim}
\normalsize
\end{listing}

\noindent
Note that the checksum on all messages to \app{uSimM200} is optional.

%===================================================================
\subsection{An Emulation Community}

The sole purpose of \app{uSimM200} is to emulate the network interface
of the M200 vehicle and as such a small MOOS community is required to
support full vehicle emulation. As shown in Figure
\ref{fig_M200_architecture}, the minimum community required is
\app{uSimM200} and \app{uSimMarine} to simulate vehicle dynamics in
response to motor commands. It is possible to augment the community
with \app{pMarineViewer} for a visualization of the simulated vehicle
independent of the controlling mission.


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

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for uSimM200}
  \label{lst_mtwo_params}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.76\textwidth}} 
    
    \pvar{port}: &amp; The IP port that \app{uSimM200} monitors for incoming 
    connections. Default is 29500. This value should only be changed when 
    running more than one emulator on the same computer; see 
    \ref{subsubsec_port} above. \\
    
  \end{longtable}
\end{listing}


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

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

\vspace{0.1in}
\begin{consoleverb}
$ uSimM200 --example or -e
\end{consoleverb}
\vspace{0.1in}
	
\vspace{0.25in}
\begin{listing}{Example configuration of the uSimM200 application}
\label{lst_mtwo_econfig}
\footnotesize
\begin{verbatim}
1   ============================================================================
2   uSimM200 Example MOOS Configuration
3   ============================================================================
4
5   ProcessConfig = uSimM200
6   {
7       AppTick    = 4
8       CommsTick  = 4
9       Port       = 29500
10  }
\end{verbatim}
\normalsize
\end{listing}

%==================================================================
\section{Publications and Subscriptions for uSimM200}
%==================================================================
\index{uSimM200!Publications and Subscriptions}
\index{Publications and Subscriptions!uSimM200}
\label{sec_simtwo_interface}

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

%==================================================================
\subsection{Variables Published by uSimM200}
\label{sec_simmtwo_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.
  
\item \mvar{THRUST\_MODE\_DIFFERENTIAL}: When commanded with \var{\$PYDIR}, 
  publishes \var{TRUE} so that \app{uSimMarine} will respond to differential 
  (thrust for left and right motors) instead of its default mode of receiving 
  rudder angle and thrust. Otherwise publishes \var{FALSE}.
  
\item \mvar{DESIRED\_THRUST\_L}: When commanded with \var{\$PYDIR}, percent 
  thrust desired in the port-side motor.
  
\item \mvar{DESIRED\_THRUST\_R}: When commanded with \var{\$PYDIR}, percent 
  thrust desired in the starboard motor.
  
\item \mvar{DESIRED\_RUDDER}: When commanded with \var{\$PYDEP}, nominal 
  rudder angle desired.
  
\item \mvar{DESIRED\_THRUST}: When commanded with \var{\$PYDEP}, nominal 
  percent thrust desired.
  
\end{packed_itemize}

%==================================================================
\subsection{Variables Subscribed for by uSimM200}
\label{sec_simtwo_subs}

The \mvar{NAV\_LAT}, \mvar{NAV\_LONG}, \mvar{NAV\_HEADING}, and 
\mvar{NAV\_SPEED} values are published by \app{uSimMarine} and are used to form 
the outgoing wire protocol messages.

\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{NAV\_LAT}: Vehicle latitude.
\item \mvar{NAV\_LAT}: Vehicle longitude.
\item \mvar{NAV\_LAT}: Vehicle heading in degrees clockwise from true north.
\item \mvar{NAV\_LAT}: Vehicle speed in meters per second.
  
\end{packed_itemize}

\end{document}

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