<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{iOS5000: A MOOS Device Driver for the OS5000 Compass}
\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.IOS5000}
\wikidoc{bugz=iOS5000}
\wikidoc{auth=ayaari@mit.edu}


%====================================================================
\section{iOS5000: A MOOS Device Driver for the OS5000 Compass}
%====================================================================
\label{sec_iOS5000}
%\index{iOS5000}

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.3\textwidth]{figures/os5000.png}
  \caption{The Ocean Server OS5000-US digital compass, shown with OEM USB 
    cable. }
  \label{fig_os5000_pic}
\end{figure}
\vspace{0.1in}

The \app{iOS5000} application is a MOOS module for interfacing with
the Ocean Server 5000 Series of digital compass units. These devices
are produced specifically for the marine autonomy market and are
relatively low-cost, small footprint (25mm x 25mm), and with low
power consumption (&lt; 30mA).  Whether through USB or direct serial
connection, they can be configured to output an ASCII-encoded data
stream. Purchasing details and technical specifications are available
on the Ocean Server website: http://ocean-server.com/compass.html .

%====================================================================
\subsection{What is being measured?}


The OS5000 device can produce measurements for Heading, pitch, roll,
temperature at the unit, and each axis can report the magnetic field
and acceleration. Currently, the \app{iOS5000} application only parses
heading, pitch, and roll. All measurements are relative to the sensor
unit. An arrow drawn on the OS5000 board indicates forward. Assuming
the device is rigidly mounted to the vehicle, reported heading, pitch,
and roll are accurate for the vehicle platform. It is possible to
adjust for rotation along the horizontal access by adjusting the
magnetic variation setting (adding or subtracting from the value
adjusting for true north).

%====================================================================
\subsection{Device Mounting}
\label{subsubsec_dev_mounting}
The OS5000 Series device should be installed as far from soft metals,
meaning metal parts that introduce magnetic interference due to innate
magnetism or when energized. This includes drive motors, batteries,
and power lines.  Calibration for hard metal (ferrous vehicle
components) is conducted through software. For Z-axis calibration, it
is necessary to rotate the compass 90 degrees so it is mounted
vertically. A convenient mount solution would offer a hinge or clever
remount that pivots the device for calibration.

%====================================================================
\section{Using the iOS5000 Application}
%====================================================================
\label{subsec_using_ios}

The typical purpose of an OS5000 Series device connected to a MOOS community is 
to provide \var{NAV\_HEADING}. It is also a useful source for pitch and roll 
values. If the unit is installed in a computing box, anonboard sensor 
conveniently reports temperature.

%====================================================================
\subsection{Serial Drivers} 

OS5000 Series devices interface with through onboard serial or USB connector 
(depending on the model). USB connections provide power; with serial, an 
external source is required. USB connections actually appear as serial 
interfaces. The connecting computer must have the FTDI driver, it is already 
installed on many systems. The website SparkFun provides installation 
instructions for several operating systems: 
https://learn.sparkfun.com/tutorials/how-to-install-ftdi-drivers/all .

%====================================================================
\subsection{Communications Protocol}

%\var{
%10 \var{\char"10}		30 \var{\char"30}		50 \var{\char"50}\\
%11 \var{\char"11}		31 \var{\char"31}		51 \var{\char"51}\\
%12 \var{\char"12}		32 \var{\char"32}		52 \var{\char"52}\\
%13 \var{\char"13}		33 \var{\char"33}		53 \var{\char"53}\\
%14 \var{\char"14}		34 \var{\char"34}		54 \var{\char"54}\\
%15 \var{\char"15}		35 \var{\char"35}		55 \var{\char"55}\\
%16 \var{\char"16}		36 \var{\char"36}		56 \var{\char"56}\\
%17 \var{\char"17}		37 \var{\char"37}		57 \var{\char"57}\\
%18 \var{\char"18}		38 \var{\char"38}		58 \var{\char"58}\\
%19 \var{\char"19}		39 \var{\char"39}		59 \var{\char"59}\\
%1A \var{\char"1A}		3A \var{\char"3A}		5A \var{\char"5A}\\
%1B \var{\char"1B}		3B \var{\char"3B}		5B \var{\char"5B}\\
%1C \var{\char"1C}		3C \var{\char"3C}		5C \var{\char"5C}\\
%1D \var{\char"1D}		3D \var{\char"3D}		5D \var{\char"5D}\\
%1E \var{\char"1E}		3E \var{\char"3E}		5E \var{\char"5E}\\
%1F \var{\char"1F}		3F \var{\char"3F}		5F \var{\char"5F}\\
%20 \var{\char"20}		40 \var{\char"40}		60 \var{\char"60}\\
%21 \var{\char"21}		41 \var{\char"41}		61 \var{\char"61}\\
%22 \var{\char"22}		42 \var{\char"42}		62 \var{\char"62}\\
%23 \var{\char"23}		43 \var{\char"43}		63 \var{\char"63}\\
%24 \var{\char"24}		44 \var{\char"44}		64 \var{\char"64}\\
%25 \var{\char"25}		45 \var{\char"45}		65 \var{\char"65}\\
%26 \var{\char"26}		46 \var{\char"46}		66 \var{\char"66}\\
%27 \var{\char"27}		47 \var{\char"47}		67 \var{\char"67}\\
%28 \var{\char"28}		48 \var{\char"48}		68 \var{\char"68}\\
%29 \var{\char"29}		49 \var{\char"49}		69 \var{\char"69}\\
%2A \var{\char"2A}		4A \var{\char"4A}		6A \var{\char"6A}\\
%2B \var{\char"2B}		4B \var{\char"4B}		6B \var{\char"6B}\\
%2C \var{\char"2C}		4C \var{\char"4C}		6C \var{\char"6C}\\
%2D \var{\char"2D}		4D \var{\char"4D}		6D \var{\char"6D}\\
%2E \var{\char"2E}		4E \var{\char"4E}		6E \var{\char"6E}\\
%2F \var{\char"2F}		4F \var{\char"4F}		6F \var{\char"6F}\\
%}

Serial communications can be configured to produce several UTF-8
output stream options.  \app{iOS5000} requires that the device is
configured to produce Format Type 0x01, prefaced with \var{\$C}, which
has similarities to NMEA-0183.  Sentences always start with the string
character (\var{\$}) and end with an asterisk (*), two checksum
characters, then \var{&lt;CR&gt;&lt;LF&gt;}. The \var{LF} character is a line feed
(ASCII decimal value 10 or \var{\char"5C n} in C-notation). The
\var{CR} character is a carriage return (ASCII decimal value 13 or
\var{\char"5C r} in C-notation).

\noindent
Sentence data is described by an uppercase delimiter followed by a
value:

\vspace{0.1in}
\begin{consoleverb}
	$Chhh.hPpp.pRrr.rTtt.t*cc
\end{consoleverb}
\vspace{0.1in}

\vspace{0.15in}
\begin{listing}{Defintiion of elements in the Format 1 sentence}
\label{lst_output_parsing}
\renewcommand{\arraystretch}{0.9}
\begin{longtable}{|p{0.1\linewidth}|p{0.2\linewidth}|p{0.1\linewidth}|p{0.5\linewidth}|}
	\hline
	{\bf Element} &amp; {\bf Range} &amp; {\bf Delim} &amp; {\bf Description} \\
	\hline
	\var{\$} &amp; - &amp; - &amp; All valid data sentences begin with '\$'. \\ %$
	\var{Chhh.h} &amp; [0.0 to 359.9] &amp; C &amp; Heading in degrees from magnetic north; 
	optionally corrected to output true north. \\
	\var{Ppp.p} &amp; [-90.0 to 90.0] &amp; 'P' &amp; Angle of pitch in degrees from 
	horizontal, positive forward. \\
	\var{Rrr.r} &amp; [-90.0 to 90.0] &amp; 'R' &amp; Angle of roll in degrees from 
	horizontal, positive to the right. \\
	\var{Ttt.t} &amp; [-45.0 to 85.0] &amp; 'T' &amp; Temperature in degrees Celsius. \\
	\hline
\end{longtable}
\end{listing}

%====================================================================
\subsection{OS5000 Device Configuration and Calibration}

{\bf The OS5000 Device must be manually configured prior to connecting
  with \app{iOS5000}.} Onboard non-volatile RAM will retain the
settings once the device is configured. Any standard serial terminal
application will connect to the OS5000. In GNU/Linux and Mac OS X, the
application \cmd{minicom} is readily available and straightforward to
use. Serial settings are: 19200 baud, 8 data bits, 1 stop bit, and no
parity (19200 8N1).

\noindent
If the GNU \var{screen} command is available, it can be used as a serial 
terminal follows:

\vspace{0.1in}
\begin{consoleverb}
	$ screen /dev/serialport 19200
\end{consoleverb}
\vspace{0.1in}

\noindent
Where \var{/dev/serialport} is the path to a valid system serial stream and 
\var{19200} is the standard baud rate of the OS5000 Series. To exit a screen 
serial session, hit \var{&lt;ctrl-A&gt;} (to signal a user command) then \var{'k'} 
(kill command) then \var{'y'} (confirm kill). Unplugging the serial or USB 
cable can be used as a last resort.

%--------------------------------------------------------------------
\subsubsection{Device Configuration}

The device can be configured with a valid serial connection. The
OS5000 user manual includes a detailed list of configuration
commands. The minimum subset needed for \app{iOS5000} are listed here
in Listing \ref{lst_config_steps}.

\vspace{0.15in}
\begin{listing}{Steps to configure the device}
  \label{lst_config_steps}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.76\textwidth}} 
    
    {\bf 1.} &amp; Press \var{&lt;esc&gt;1&lt;space&gt;} to indicate format 1 sentences. \\
    
    {\bf 2.} &amp; Press \var{&lt;esc&gt;R5&lt;space&gt;} to set a 5Hz output rate. Replace 
    '5' with another value up to 40. 0 will stop output. Negative numbers 
    (up to -50) are seconds per sample. \\
    
    {\bf 3.} &amp; Press \var{&lt;esc&gt;X15&lt;space&gt;} to turn set heading, pitch, 
    roll, and temperature in the device output sentence. \\
    
  \end{longtable}
\end{listing}

%--------------------------------------------------------------------
\subsubsection{Calibration}

OS5000 Series devices are factory calibrated for testing at the manufacturing 
facility and are otherwise meaningless. {\bf The compass can be considered 
unreliable until is calibrated while mounted in the vehicle.} User calibrations 
are available for hard iron (ferrous sources on the vehicle it is attached to) 
in the X,Y planes and separately for hard iron in the Z plane. Temperature can 
optionally be calibrated.

The user manual describes the process details. In summary, the device is placed 
in calibration mode and spun around until the output indicates that sufficient 
data has been gathered. While calibrating, the vehicle must be kept away from 
any metal objects; it must remain completely horizontal while being spun 
around. The Z-axis calibration can be difficult because it requires rotating 
the unit 90 degrees before taking samples. See the mounting section 
(\ref{subsubsec_dev_mounting}) above for suggestions to facilitate Z-axis 
calibration.

%===================================================================
\subsection{Configuration Parameters for iOS5000}
%\index{iOS5000!Configuration Parameters}
%\index{Configuration Parameters!iOS5000}

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for iOS5000}
\label{lst_ios_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 
  
  \pvar{prefix}: &amp; (optional, default = \var{COMPASS\_}) Message names
  published by \app{iOS5000} will be prefixed by this string. If not
  included, an underscore will inserted as the last prefix
  character. If a blank value is rovided, no prefix or underscore will
  precede variable name in the publication. \\
  
  \pvar{port}: &amp; (required) Fully-qualified path to the operating
  system's serial stream for the device. Example:
  \var{/dev/ttyUSB.3-2.1:1.0} \\
  
  \pvar{baudrate}: &amp; (optional, default = \var{19200}) Serial
  communications baud rate, must be one of \var{2400}, \var{4800},
  \var{9600}, \var{19200}, \var{38400}, \var{57600}, or
  \var{115200}. \\
  
  \pvar{speed}: &amp; Deprecated. Alternative name for \pvar{baudrate}. \\
  
  \pvar{mag\_var}: &amp; (optional, default = \var{0.0}) Heading
  publications are offset by this value. Typically used to adjust for
  adjusting magnetic to true north. Can also be used to adjust for
  mounting angle.  \\
  
  \pvar{prerotation}: &amp; Deprecated. Alternative name for \pvar{mag\_var}. 
  \\
  
\end{longtable}
\end{listing}


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

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

\vspace{0.1in}
\begin{consoleverb}
	$ iOS5000 --example or -e
\end{consoleverb}
\vspace{0.1in}

\vspace{0.25in}
\begin{listing}{Example configuration of the iOS5000 application}
\label{lst_ios_econfig}
\footnotesize
\begin{verbatim}
1   ============================================================================
2   iOS5000 Example MOOS Configuration
3   ============================================================================
4
5   ProcessConfig = iOS5000
6   {
7       AppTick    = 4
8       CommsTick  = 4
9       Prefix     = COMPASS_       // Prepends this to all output message names
10      Port       = /dev/ttyACM1   // Fully-qualified path to the serial port
11      Baudrate   = 19200          // Serial port baud rate
12      Mag_Var    = 0.0            // Magnetic variation in degrees to offset
13                                  // heading so it reports relative to true N
14  }
\end{verbatim}
\normalsize
\end{listing}

%=============================================================
\section{Publications and Subscriptions for iOS5000}
%=============================================================
%\index{iOS5000!Publications and Subscriptions}
%\index{Publications and Subscriptions!iOS5000}
\label{sec_ios_interface}

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

%=============================================================
\subsection{Variables Published by iOS5000}
\label{sec_ios_pubs}

\noindent
The mission file parameter \pvar{prefix} defines the \mvar{[prefix]}
text in the list of MOOS message publications below. For example, if
\pvar{prefix}=\pvar{COMPASS\_}, heading is published under the name
\mvar{COMPASS\_HEADING}.

\begin{packed_itemize}[2]
	
\item \mvar{[prefix]\_HEADING}: Heading in degrees clockwise from magnetic 
  north, plus an offset as defined in \pvar{Mag\_Var} parameter in the 
  mission file.
  
\item \mvar{[prefix]\_PITCH}: Rotation of the sensor forward/back. Positive 
  values indicate pitching with the nose down, negative with the tail down.
  
\item \mvar{[prefix]\_ROLL}: Rotation of the sensor left/right. Positive 
  values indicate pitching with the right side down, negative with the left 
  side down.
  
\item \mvar{[prefix]\_TEMPERATURE}: Temperature in Celsius at the device.
  
\end{packed_itemize}

%------------------------------------------------------------------
\subsection{Variables Subscribed for by iOS5000}
\label{sec_ios_subs}

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