<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{iM300 Payload Autonomy Interface for Heron USVs}
\vspace{0.1in}
\labdate{Spring 2022}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=PavLab.IM300}
\wikidoc{bugz=iM300}
\wikidoc{auth=mikerb@mit.edu}

%====================================================================
\section{iM300 Payload Autonomy Interface for Heron USVs}
%====================================================================
\label{sec_iM300}
\index{iM300}

The \app{iM300} application is a driver that interfaces a MOOS
community to the Clearpath Robotics Heron M300 vehicle. The onboard
front-seat computer manages vehicle actuation per received
instructions. Using a documented wire protocol, thrust commands from
an outside entity are published to the front-seat via an IP port on
its Ethernet interface. The vehicle returns data from on board
navigation sensors and limited health status. The sequence of events
are described in Figure \ref{fig_im300_diag} below.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/iM300_diag.png}
  \caption{{\bf The iM300 App:} Provides an interface between a
    MOOS-IvP payload autonomy community, and the front seat computer
    on a Heron M300 unmanned surface vehicle. (1) Heading and speed
    commands are produced by the helm at about 4Hz. (2) The desired
    heading and speed commands are consumed bythe PID controller. (3)
    The PID produces desired rudder and thrust commands at about
    10Hz. (4) The desired rudder and thrust commands are consumed by
    \appp{iM300}. (5) Desired thrust left/right commands suitable for
    the differential drive thrusters on the Herons, is produced by
    \app{iM300} and posted as NMEA messages over a configured IP
    address and port. (6) Desired thrust left/right commands are sent
    to the Heron thrusters. In the other direction (7), GPS information
    is sent to the Heron front seat interface and, (8), sent over
    the \app{iM300} NMEA interface to the payload computer where it
    is used to make the next helm decision.}
\label{fig_task_manager}
\end{figure}
\vspace{0.1in}

\noindent
Although the figure describes a sequence of events, each app is
publishing and consuming information asynchronously at different rates.
There is no guarantee regarding how many messages, if any are processed
or produced on any given iteration of any of the modules described.

%====================================================================
\section{Thrust Modes}
\label{sec_im300_modes}

There are three thrust modes supported by \app{iM300}. The \var{normal} mode (default),
and the \var{aggro} and \var{rotate} modes. They are set with the \pvar{thrust\_mode}
configuration parameter.

%====================================================================
\subsection{The Normal Thrust Mode}

In the \var{normal} thrust mode, the values for \var{thrust\_left} and
\var{thrust\_right} are chosen using the following. First a delta
value is calculated:

$$ \delta = \frac{{\tt desired\_thrust} * {\tt desired\_rudder}} {{\tt max\_rudder}} $$

\vspace{0.1in}
\noindent
Using the delta value, this determines the thrust differential as follows:

$$ {\tt thrust\_left} = {\tt desired\_thrust} - \delta $$

$$ {\tt thrust\_right} = {\tt desired\_thrust} + \delta $$

\vspace{0.1in}
\noindent
Finally the \var{thrust\_left} and \var{thrust\_right} values are clipped to be
in the range of $[0,100]$

%====================================================================
\subsection{The Aggro Thrust Mode}

To Be Documented

%====================================================================
\subsection{The Rotate Mode}

To Be Documented



%====================================================================
\section{Vehicle Position}
%====================================================================
The Clearpath controller in the M300 front-seat receives sentences from the 
GPS, digital compass, and IMU. A filter estimates pose and position, packages 
data into the wire protocol format, then pushes the data over the IP 
interface. The \app{iM300} application receives the 5Hz updates, parses 
incoming position data, then publishes the following messages:

\vspace{0.15in}
\begin{tabular}{| l l |} \hline
  {\bf message name} &amp; {\bf Description} \\ \hline
  \mvar{[prefix]\_X} &amp; X-position on the local grid (based on current 
  lat-lon) \\
  \mvar{[prefix]\_Y} &amp; Y-position on the local grid (based on current 
  lat-lon)\\
  \mvar{[prefix]\_LAT} &amp; Latitude, as reported by the Clearpath controller \\
  \mvar{[prefix]\_LON} &amp; Longitude, as reported by the Clearpath controller \\
  \mvar{[prefix]\_SPEED} &amp; Speed over ground, as reported by the Clearpath 
  controller \\
  \mvar{[prefix]\_HEADING} &amp; Heading,as reported by the Clearpath controller 
  \\
  \hline
\end{tabular}
\vspace{0.15in}

\noindent
Each message name is preceded by \mvar{[prefix]}, a string value set in the 
\pvar{GPS\_PREFIX} mission file parameter. By default, the prefix is 
\pvar{NAV\_}, making iM300 the source of \mvar{NAV\_*} variables removing the 
need for a dedicated GPS or digital compass interface MOOS module.

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

The \app{iM300} 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{iM300}:

\vspace{0.15in}
\begin{listing}{Configuration Parameters for iM300}
\label{lst_mtwo_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 
  
  \pvar{ip\_addr}: &amp; The IPv4 address of the M300 front-seat computer
  that is being interfaced with. Default value is \pvar{localhost},
  which implies that the \app{iM300} application is being run on the
  front-seat vehicle itself. \\
  
  \pvar{port}: &amp; At the defined \pvar{ip\_address}, this is the port
  number to communicate with the vehicle. \\
  
  \pvar{drive\_mode}: &amp; \pvar{normal}, \pvar{aggro} or \pvar{rotate}. \\
  
  \pvar{max\_rudder}: &amp; \mvar{DESIRED\_RUDDER} will be constrained to this 
  value ($+$ or $-$) when converted to thrust values for the front-seat. 
  Value must be a real number greater than $0.0$ and less than $180.0$. 
  Default value is $50.0$. \\
  
  \pvar{max\_thrust}: &amp; \mvar{DESIRED\_THRUST} will be constrained to this 
  value when converted to thrust values for the front-seat. Value must be a 
  real number greater than $0.0$ and less than or equal to $100.0$. Default 
  value is $100.0$. \\

  \pvar{ignore\_msg}: &amp; \\
  \pvar{heading\_source}: &amp; \\
  \pvar{}: &amp; \\
  \pvar{ignore\_checksum\_errors}: &amp; \\
  \pvar{stale\_nav\_msg\_thresh}: &amp; \\
  \pvar{stale\_thresh}: &amp; \\
  \pvar{comms\_type}: &amp; \\

  \pvar{gps\_prefix}: &amp; This string is inserted at the start of X, Y, 
  heading, and speed publications. Default is \pvar{nav\_}. The underscore 
  will be added if not supplied in the mission file. \\
  
  \pvar{nav\_prefix}: &amp; \\

  \pvar{compass\_prefix}: &amp; \\
  
\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}
$ iM300 --example or -e
\end{consoleverb}
\vspace{0.1in}

\vspace{0.25in}
\begin{listing}{Example configuration of the iM300 application}
\label{lst_mtwo_econfig}
\footnotesize
\begin{verbatim}
1   ============================================================================
2   iM300 Example MOOS Configuration
3   ============================================================================
4
5   ProcessConfig = iM300
6   {
7   AppTick        = 10
8   CommsTick      = 10
9
10  port           = 29500
11  ip_addr        = localhost // Default is 'localhost'
12  gps_prefix     = NAV_      // Prepended to GPS position messages.
15
17  PUBLISH_RAW    = false     // When true, publish all messages from
18                             // front seat to M300_RAW_NMEA
19  MAX_RUDDER     = 50.0      // Rudder value will be capped to this, +/-
20  MAX_THRUST     = 100.0     // Thrust value to each motor will be
21                             // capped to this value, +/-
22  PUBLISH_THRUST = false     // When true, publishes M300_THRUST_L and _R
23  }
\end{verbatim}
\normalsize
\end{listing}

%=============================================================
\section{Publications and Subscriptions for iM300}
\index{iM300!Publications and Subscriptions}
\index{Publications and Subscriptions!iM300}
\label{sec_mtwo_interface}

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

%---------------------------------------------------------------------
\subsection{Variables Published by iM300}
\label{sec_mtwo_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{[prefix]\_X}: Last reported X position of the vehicle, in
  meters east or west of the MOOS origin.
  
\item \mvar{[prefix]\_Y}: Last reported Y position of the vehicle, in 
  meters north or south of the MOOS origin.
  
\item \mvar{[prefix]\_LAT}: Last reported latitude of the vehicle, in
  decimal degrees.
  
\item \mvar{[prefix]\_LON}: Last reported longitude of the vehicle, in 
  decimal degrees.
  
\item \mvar{[prefix]\_SPEED}: Last reported vehicle speed over ground, in 
  meters per second.
  
\item \mvar{[prefix]\_HEADING}: Last reported vehicle heading, in degrees 
  clockwise from true north. Will be offset by \pvar{heading\_offset}, if 
  defined.
  
\item \mvar{M300\_BATTERY\_VOLTAGE}: Last reported battery voltage, in 
  volts.
  
\item \mvar{M300\_RAW\_NMEA}: If \pvar{publish\_raw}=\pvar{true}, all 
  incoming Clearpath wire protocol messages will be published to this MOOS 
  message. Note that \app{iM300} will continue to process messages when 
  publishing raw.
  
\item \mvar{M300\_THRUST\_L}: Published at the time a thrust command is 
  sent to the vehicle, if mission parameter 
  \pvar{publish\_thrust}=\pvar{true} Value is the actual percent thrust 
  requested at the left thruster. \\
  
\item \mvar{M300\_THRUST\_R}: Published at the time a thrust command is 
  sent to the vehicle, if mission parameter 
  \pvar{publish\_thrust}=\pvar{true} Value is the actual percent thrust 
  requested at the right thruster.  \\
  
\end{packed_itemize}

%------------------------------------------------------------------
\subsection{Variables Subscribed for by iM300}
\label{sec_mtwo_subs}

The \app{iM300} always subscribes for appcasting events:

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

\noindent
When in {\bf direct thrust} mode, \app{iM300} listens for commands to
be sent directly to the motors:

\begin{packed_itemize}[2]
	
\item \mvar{DESIRED\_THRUST\_L}: Push this percent thrust value to the
  vehicle for commanding the left thruster. Constrained by \app{iM300}
  to $-100.0 and 100.0$.
  
\item \mvar{DESIRED\_THRUST\_R}: Push this percent thrust value to the
  vehicle for commanding the right thruster. Constrained by
  \app{iM300} between $-100.0 and 100.0$.
	
\end{packed_itemize}

\noindent
When in {\bf Ruddder thrust} mode, \app{iM300} listens for commands to
be sent directly to the motors:

\begin{packed_itemize}[2]
	
\item \mvar{DESIRED\_THRUST}: Percent thrust requested of the
  vehicle. When combined with the \mvar{DESIRED\_RUDDER} value, is
  used to calculate percent thrust for each motor. Constrained by
  \app{iM300} between the value set in mission file parameter
  \pvar{max\_thrust} and $0 -$ the value.
  
\item \mvar{DESIRED\_RUDDER}: Notional rudder angle requested of the
  vehicle. When combined with the \mvar{DESIRED\_THRUST} value, is
  used to calculate percent thrust for each motor. Constrained by
  \app{iM300} to between the value set in mission file parameter
  \pvar{max\_rudder} and $0.0 -$ the value.
  
\end{packed_itemize}

%==================================================================
\section{Appendix: NMEA Messages for the Heron M300}
%==================================================================
\label{sec_m3_msgs}

%==================================================================
\subsection{NMEA Messages In Use In Practice}

\subsubsection*{Vehicle Pose: \$CPNVG}

\var{\$CPNVG}: Current Pose: The current pose and position as
estimated by a filter running on the vehicle. Takes GPS, digital compass, and
possibly IMU into account. 

\vspace{0.1in}
\noindent
\var{\$CPNVG,1,2,3,4,5,6,7,8,9,10,11,12,*HH}

\begin{packed_enumerate}
\item \var{[Timestamp]}: Timestamp of the sentence
\item \var{[Lat\_NMEA]}: Calculated latitude, in NMEA format
\item \var{[LatNS\_NMEA]}: Hemisphere (N or S) of latitude
\item \var{[Lon\_NMEA]}: Calculated longitude, in NMEA format
\item \var{[LonEW\_NMEA]}: Hemisphere (E or W) of longitude
\item \var{[PosQual]}: Quality of position estimate (no GPS = 0, otherwise = 1)
\item \var{[AltBottom]}: Altitude in meters from bottom, for surface vehicles this field is blank
\item \var{[DepthTop]}: Depth in meters from top, for surface vehicles this field is blank
\item \var{[Heading]}: Direction of travel in degrees clockwise from true north
\item \var{[Roll]}: Degrees of roll
\item \var{[Pitch]}: Degrees of pitch
\item \var{[NavTimestamp]}: Timestamp for time this pose/position was calculated. If blank, use [Timestamp].
\end{packed_enumerate}

\vspace{0.1in}
\noindent
Example: \var{\$CPNVG,081025.987,4221.81092,N,07106.84603,W,1,,,203.1,3.4,4.5,081025.980*5B}

%-----------------------------------------------------------------------
\subsubsection*{Battery Level: \$CPRBS}

One sentence is published for every bank of cells:

\vspace{0.1in}
\noindent
\var{\$CPRBS,1,2,3,4,5,6*HH}

\vspace{0.1in}
\begin{packed_enumerate}
\item \var{[Timestamp]}: Timestamp of the sentence.
\item \var{[ID\_Battery]}: Unique ID number of the battery being reported on.
\item \var{[V\_Batt\_Stack]}: Voltage of the battery bank.
\item \var{[V\_Batt\_Min]}: Lowest voltage read from cells in the bank.
\item \var{[V\_Batt\_Max]}: Highest voltage read from
\end{packed_enumerate}

%-----------------------------------------------------------------------
\subsubsection*{Raw IMU Data: \$CPRMC}

Data is read from the compass sensor by the vehicle and repackaged into this sentence

\vspace{0.1in}
\noindent
\var{\$CPRCM,1,2,3,4,5,6*HH}


\vspace{0.1in}
\begin{packed_enumerate}
\item \var{[Timestamp]}: Timestamp of the sentence
\item \var{[ID\_Compass]}: Unique ID number of the compass being reported on
\item \var{[Heading]}: Raw reading from compass for degrees clockwise from true north
\item \var{[Pitch]}: Raw reading from compass for degrees of pitch
\item \var{[Roll]}: Raw reading from compass for degrees of roll
\item \var{[NavTimestamp]}: Timestamp for time compass reported this data. If blank, use [Timestamp]
\end{packed_enumerate}
  
\end{document}

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