<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{iButtonBox Documentation}
\vspace{0.1in}
\labdate{Fall 2017}
\vspace{0.1in}
\labauth{Oliver MacNeely, oliverm@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

% Wikifile naming convention:
% prefix=PavLab.
% suffix is app name with first letter uppercase
\wikidoc{file=PavLab.IButtonBox}
\wikidoc{bugz=iButtonBox}
\wikidoc{auth=oliverm@mit.edu}

%====================================================================
\section{iButtonBox Overview}
%====================================================================
\label{sec_iButtonBox}

The button box is a physical device that allows button-based input
into MOOS apps. Through the programming of four different buttons, a
user can have each button correspond to the state of a variable, which
is then posted to the MOOS database, where pushing a button will
update the given variable with a binary value (true/false).

%\vspace{0.1in}
%\begin{figure}[H]
%  \centering 
%  \includegraphics[width=0.4\textwidth]{figures/topology.png}
%  \caption{{\bf Typical uFldHazardMetric Topology:} This module runs on
%    the shoreside, alongside the hazard sensor typically, and receives
%    hazazardset reports from the vehicle bridge with the
%    \mvvar{HAZARDSET\_REPORT} variable. Evaluations may be seen via the
%    appcast output of \app{uFldHazardMetric}, or in the log file.}
%  \label{fig_pexample_overview}
%\end{figure}

%====================================================================
\section{Setting up the ButtonBox}
%====================================================================

The ButtonBox consists of two parts, the arduino inside of it and
several buttons on the outside. Setting up the ButtonBox takes several
steps: uploading code to the arduino, connecting it to the computer,
and ensuring connection to the MOOS database.

%====================================================================
\subsection{Uploading code to the Arduino}

The first step is to download the most recent version of the Arduino
IDE which is freely available online. After downloaded, open the
application and open the file at
\emph{moos-ivp-aquaticus/trunk/src/iButtonBox/ButtonBox.ino} within
the IDE. Then plug the Arduino into your computer and, from the
â€œToolsâ€ dropdown menu in the Arduino IDE toolbar, select the correct
model (Tools/Board) and correct port (Tools/Port ) that the Arduino is
connected to. Once these are chosen, upload the code to the Arduino
with the arrow button and reconnect the Arduino to the button box case
(if it was taken out to upload code).

%====================================================================
\subsection{Connecting the ButtonBox}

After uploading the code to the Arduino, connect the assembled button
box to the mokai or computer that it is being used with. Then open the
terminal on this device and look in the directory \emph{/dev/} for a
device with a name of the form:

\begin{center}
tty.usbmodemXXXXX 
\end{center}

\begin{center}
(where XXXXX stands in for numbers)
\end{center}

Keep track of this number for use in the .moos configuration file for the iButtonBox application. If multiple devices exist, unplugging other usb input devices and then navigating to \emph{/dev} might help.

%====================================================================
\section{Using the iButtonBox Application}
%====================================================================
\label{subsec_using_iButtonBox}


%====================================================================
\subsection{Receiving Mail}

The iButtonBox applications receives no mail from any MOOS apps, but
does receieve data from the connected arduino via string-type messages
that it parses. The standard user shouldn't have to worry about this
communication or interact with it.

%====================================================================
\subsection{Configuration Parameters of pExample}

The iButtonBox app has three different configuration parameters:
\pvar{PORT}, \pvar{BAUDRATE}, and \pvar{BUTTON\_X\_NAME}.

\vspace{0.1in}
\noindent
Note the quick-listing of parameters is given in Section
\ref{sec_ibb_params}.

%-------------------------------------------------------------------
\subsubsection{The \pvar{PORT} Configuration Parameter}
\label{sec_ibb_port_param}

This configuration parameter is used to tell the iButtonBox
application the correct adress to read serial input from. The correct
value for this parameter is the adress of the arduino plugged into the
computer. This will be of the form

\begin{center}
\emph{/dev/tty.usbmodemXXXXX} 
\end{center}

Where XXXXX is the number that we found when we checked \emph{/dev}
for the correct device.

%-------------------------------------------------------------------
\subsubsection{The \pvar{BAUDRATE} Configuration Parameter}
\label{sec_ibb_baud_param}

This configuration parameter is used to control the rate of
information transfer between the arduino and the computer and should
always be given a value of 9600.

%-------------------------------------------------------------------
\subsubsection{The \pvar{BUTTON\_X\_NAME} Configuration Parameter}
\label{sec_ibb_button_param}

This parameter changes depending on the number of buttons that you are
controlling and the function of each button. Currently buttons are
only used for updating variable values in the MOOS database with a
value of "TRUE" or "FALSE". In order to control the function of a
button, change the \emph{X} in the parameter name to a value from 0 to
3 (0 is red, 1 is blue, etc). Then set the value for this parameter to
the name of the variable that you would like the button to update upon
being pressed.


%===================================================================
\section{Configuration Parameters for iButtonBox}
%====================================================================
\label{sec_ibb_params}
% The index info is included if this document becomes part of a larger work

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for iButtonBox}
  \label{lst_mtwo_params}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.76\textwidth}} 
    
    \pvar{PORT}: &amp; The port to which the arduino is connected. It can
    change each time the ButtonBox is unplugged and plugged back in
    and should be checked by looking at the contents of
    \emph{/dev}. It will be of the form
    \emph{/dev/tty.usbmodemXXXXX}. See Section
    \ref{sec_ibb_port_param}. \\
    
    \pvar{BAUDRATE}: &amp; The rate at which information is transferred
    via serial between the arduino and the computer, its value should
    be 9600.  See Section \ref{sec_ibb_baud_param} \\

    \pvar{BUTTON\_X\_NAME}: &amp; This parameter allows the user to define
    which button corresponds to which MOOS variable. The parameter
    will be of the form \pvar{BUTTON\_X\_NAME} where \emph{X} will be
    a button number (0-3). The value will take the form of the
    variable that the button will correspond to. See Section
    \ref{sec_ibb_button_param} \\
        
  \end{longtable}
\end{listing}

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

An example MOOS configuration block is provided in Listing
\ref{lst_ibb_econfig} below. 

\vspace{0.25in}
\begin{listing}{Example configuration of the iButtonBox application}
\label{lst_ibb_econfig}
\footnotesize
\begin{verbatim}
1   ============================================================================
2   iButtonBox Example MOOS Configuration
3   ============================================================================
4
5   ProcessConfig = iButtonBox
6   {
7     AppTick        = 50
8     CommsTick      = 50
9
10    PORT = /dev/tty.usbmodemXXXXX
11    BAUDRAET = 9600
12    BUTTON_X_NAME = VARIABLE_NAME
23  }
\end{verbatim}
\normalsize
\end{listing}

%=============================================================
\section{Publications and Subscriptions for iButtonBox}
\label{sec_ibb_interface}

The interface for \app{iButtonBox}, in terms of publications and
subscriptions, is described below. 
%---------------------------------------------------------------------
\subsection{Variables Published by iButtonBox}
\label{sec_ibb_pubs}

\begin{packed_itemize}[2]
  
\item \mvar{EXAMPLE\_VARIABLE}: Publishes a TRUE or FALSE value for
  for each variable assigned in config.
 
\end{packed_itemize}

%------------------------------------------------------------------
\subsection{Variables Subscribed for by iButtonBox}
\label{sec_ibb_subs}

The \app{iButtonBox} doesn't subscribe for any variables.

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

The \app{iButtonBox} application produces some useful information to
the terminal on every iteration of the application. An example is
shown in Listing \ref{lst_ibb_appcast} below. This application is also
appcast enabled, meaning its reports are published to the MOOSDB and
viewable from any \app{uMAC} application or \app{pMarineViewer}.

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{iButtonBox}}
\label{lst_ibb_appcast}
\footnotesize
\begin{verbatim}
  1  ===================================================================
  2  iButtonBox alpha                                             0/0(442)
  3  ===================================================================
  4  SETUP 
  5  -----
  6  	  	  	PORT: /dev/tty.usbmodem14311
  7  	  	  	BAUDRATE: 9600
  8  		
  9  STATUS
 10  -----
 11  	  	  	Valid serial connection: true       
 12                 
 13  	  	  	No current button values.     
 14  

\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The first few lines (6-7) show the configuration settings for
\app{iButtonBox}.  The setup status of \app{iButtonBox} is shown in
Lines 9-13. The second status block, lines 15-21, indicate whether the
arduino is connected (valid serial connection) and the values of the
buttons.

%===========================================================
\section{Troubleshooting}
%===========================================================
\label{sec_ibb_troubleshooting}

When dealing with errors regarding the ButtonBox and communication
with both the computer it is plugged into and/or the MOOS database,
the best course of action is to make sure that all wires and cables
are securely attached and then to unplug and plug back in the
ButtonBox, relaunching MOOSDB and double-checking the port of the
arduino along the way. This should reset communication and alleviate
any errors. Other issues should only occur with misconfigured
configuration blocks.

\end{document}

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