<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{iLEDInfoBar Documentation}
\vspace{0.1in}
\labdate{Spring 2018}
\vspace{0.1in}
\labauth{Caileigh Fitzgerald, caileigh@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.ILEDInfoBar}
\wikidoc{bugz=iLEDInfoBar}
\wikidoc{auth=caileighm@mit.edu}

%====================================================================
\section{iLEDInfoBar Overview}
%====================================================================
\label{sec_iLEDInfoBar}
\index{iLEDInfoBar}

Relevant terms: 
  LED:  refers to the integrated LED board with, RGB LED, 3 inputs and 3 outputs. When used in plural, it refers to the individually addressable LEDs wired as a strip.
  Icon:  refers to the silhouette design that is created by laser cut acrylic with an RGB LED light shining through. Icon will be used to describe one LED covered by one Piece of acrylic.
  Enclosure:  refers to the case that is created using laser cut acrylic.
  LEDInfoBar:  refers to the whole device assembled. 
  Brackets:  refers to the metal pieces uses to attach the LED bar to the cockpit of the Mokai (Motorized kayak used in Aquaticus experiments.)
  TeensyLC:  refers to the micro controller used in the LEDInfoBar. TeensyLC is not an official Arduino product. (see list at the end for other compatible micro contollers.)
 
The LEDInfoBar is a physical device that uses LEDs to indicate game states in an Aquaticus experiment. Icons are created by overlapping the LED with laser cut acrylic, creating a silhouette effect. During the game a participant will be able to look at the LEDInfoBar and ascertain their state. e.g. * was in proximity of enemy and was tagged *  the â€œTaggedâ€ icon would be lit up indicating to the participant that they are currently tagged.

The icons represent these games states;
\emph{Out of Bounds}
\emph{Tagged}
\emph{In Flag Zone}
\emph{Have Flag}
\emph{In Tag Zone}

Each icon corresponds to the state of a variable, which iLEDInfoBar subscribes to. iLEDInfoBar is run on the vehicle computer. The vehicle receives variables from the shoreside community via the uFldMessageHandler. These variables are then parsed by the iLEDInfoBar MOOS app, then, commands are sent over serial to the microcontroller running the LEDInfoBar.

%\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 LEDInfoBar}
%====================================================================

The LEDInfoBar consists of five parts;
1.) TeensyLC generally housed inside the buttonbox enclosure. (see list at end for other compatible micro controllers)
2.) 5 individually addressable LEDs wired in a strip.
3.) 5 Icons 
4.) Acrylic enclosure 
5.) Metal brakets

Setting up the LEDInfoBar for the first time takes several steps;
â€¢ Flashing the TeensyLC with the code found in the /src/iLEDInfoBar/iLED_arduino_code directory
â€¢ Gathering material to make the LED strip, enclosure, icons and brackets. 
â€¢ Assembling the LEDInfoBar (covered later on.)
â€¢ Running an alpha_LED mission and ensuring connection to the MOOS database.
â€¢ Attaching brackets to cockpit of vehicle.
â€¢ Allocating a physical USB port on the vehicle computer, as well as a 5V USB external power source. (2.2A OR 2.4A are fine.) 

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

Option 1: Use Arduino IDE to flash TeensyLC.
The first step is to download the most recent version of the Arduino IDE which is freely available on-line. After downloaded, open the application and open the file at \emph{moos-ivp-aquaticus/trunk/src/iLEDInfoBar/iLED_arduino_code/iLEDInfoBar.ino}
within the IDE. Then plug the TeensyLC into your computer using a micro USB cable that supports data transfer. Then from the Tools dropdown menu in
the Arduino IDE toolbar, select the correct model (Tools/Board) â€œTeensyLCâ€ and correct port (Tools/Port ) that the TeensyLC is connected to. 
e.g. \emph{/dev/cu.usbmodem00000}  Once these are chosen, upload the code to the TeensyLC using sketch/upload in the drop down menu.

Option 2: Use command line to flash TeensyLC.
https://playground.arduino.cc/Learning/CommandLine
// I am working on these instructions. Almost done

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

After uploading the code to the TeensyLC, connect it to the assembled LEDInfoBar. Then connect the LEDInfoBar to the computer that it is being used with. There are a few way to find/setup the correct serial port for the Arduino; 

Option 1:  Searching the \emph{/dev/} directory
Open the terminal on the device used in the vehicle 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}

The serial port needs to be put in the .moos configuration file for the iLEDInfoBar application i.e. PORT = tty.usbmodemXXXXX.
If multiple devices exist, unplugging other USB input devices and then navigating to \emph{/dev/} might help.

Option 2:  uDev Rules
uDev creates a symlink so that when you connect the TeensyLC configured in the rules.d file, the port stays the same for the computer itâ€™s set up on. Allowing .moos configuration files to contain a symlink to the serial port.
For uDev rules to work you need a configuration file to be placed in \emph{/etc/udev/rules.d/}

An example uDev file is in \emph{/src/iLEDInfoBar/iLED_arduino_code/rules.d}

%====================================================================
\section{Using the iLEDInfoBar Application}
%====================================================================
\label{subsec_using_iLEDInfoBar}


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

This section needs work. I initially was too Aquaticus heavy with my example.

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

The iLEDInfoBar app has eight different configuration parameters:

\pvar{PORT}, \pvar{BAUDRATE}, \pvar{TEAM_COLOR}, \pvar{TAGGED}
\pvar{OUT_OF_BOUNDS}, \pvar{HAVE_FLAG}, \pvar{IN_TAG_RANGE}, and \pvar{IN_FLAG_ZONE}.

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

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

This configuration parameter is used to tell the iLEDInfoBar
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_iled_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{TEAM_COLOR} Configuration Parameter}
\label{sec_iled_team_color_param}
This configuration parameter is under utilized. It leaves the option for different effects with the LEDInfoBar dependent on the team.

%-------------------------------------------------------------------
\subsubsection{The \pvar{TAGGED} Configuration Parameter}
\label{sec_iled_tagged_param}
This configuration parameter defines the name of the variable which will publish when the vehicle with the LEDInfoBar is â€œTAGGEDâ€.
  The vehicle is â€œtaggedâ€ when it gets within 3 meters of an enemy on the enemy side of the field. A vehicle is also â€œtaggedâ€ when it goes out of bounds.


%-------------------------------------------------------------------
\subsubsection{The \pvar{OUT_OF_BOUNDS} Configuration Parameter}
\label{sec_iled_out_of_bounds_param}
This configuration parameter defines the name of the variable which will publish when the vehicle with the LEDInfoBar is â€œOUT_OF_BOUNDSâ€.
  The vehicle is â€œout of boundsâ€ when it has left the op region. This is set in a shoreside config file.


%-------------------------------------------------------------------
\subsubsection{The \pvar{HAVE_FLAG} Configuration Parameter}
\label{sec_iled_have_flag_param}
This configuration parameter defines the name of the variable which will publish when the vehicle with the LEDInfoBar has the flag, â€œHAVE_FLAGâ€.
  The vehicle â€œhas the flagâ€ when it has successfully entered the flag zone, requested a â€œgrabâ€ before leaving the flag zone. In other words itâ€™s on its way to score with the flag.


%-------------------------------------------------------------------
\subsubsection{The \pvar{IN_TAG_RANGE} Configuration Parameter}
\label{sec_iled_in_tag_range_param}
This configuration parameter defines the name of the variable which will publish when the vehicle with the LEDInfoBar is, â€œIN_TAG_RANGEâ€.
  This is purely and offensive indicator. A defensive indicator is an option but is not currently implemented. The vehicle is in â€œtag rangeâ€ when it is on itâ€™s side of the field and an enemy vessel is within 3 meters of their vessel. This does not mean they are requesting a tag. It only means they are within range to do so successfully.


%-------------------------------------------------------------------
\subsubsection{The \pvar{IN_FLAG_RANGE} Configuration Parameter}
\label{sec_iled_in_flag_range_param}
This configuration parameter defines the name of the variable which will publish when the vehicle with the LEDInfoBar is, â€œIN_FLAG_RANGEâ€.
The vehicle is â€œin the flag zoneâ€ when it is within 10 meters of the enemy flag. This does not mean they are requesting a â€œgrabâ€. It only means they are within range to do so successfully.



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

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for iLEDInfoBar}
  \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 LEDInfoBar 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_iled_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_iled_baud_param} \\

    \pvar{TEAM_COLOR}: &amp; This configuration parameter is under utilized. 
    It leaves the option for different effects with the LEDInfoBar dependent on the team.
    \ref{sec_iled_team_color_param} \\

    \pvar{TAGGED}: &amp; This configuration parameter defines the name of the variable 
    which will publish when the vehicle with the LEDInfoBar is â€œTAGGEDâ€.
    The vehicle is â€œtaggedâ€ when it gets within 3 meters of an enemy on the 
    enemy side of the field. A vehicle is also â€œtaggedâ€ when it goes out of bounds.
    \ref{sec_iled_tagged_param} \\

    \pvar{OUT_OF_BOUNDS} &amp; This configuration parameter defines the name of the 
    variable which will publish when the vehicle with the LEDInfoBar is â€œOUT_OF_BOUNDSâ€.
    The vehicle is â€œout of boundsâ€ when it has left the op region. 
    This is set in a shoreside config file.
    \ref{sec_iled_out_of_bounds_param} \\

    \pvar{HAVE_FLAG} &amp; This configuration parameter defines the name of the 
    variable which will publish when the vehicle with the LEDInfoBar has the flag, â€œHAVE_FLAGâ€.
    The vehicle â€œhas the flagâ€ when it has successfully entered the flag zone, 
    requested a â€œgrabâ€ before leaving the flag zone. In other words itâ€™s on its way to score with the flag.
    \ref{sec_iled_have_flag_param} \\

    \pvar{IN_TAG_RANGE} Configuration Parameter} &amp; This configuration parameter defines the name of the variable which will publish when the vehicle with the LEDInfoBar is, â€œIN_TAG_RANGEâ€.
    This is purely and offensive indicator. A defensive indicator is an option but is not currently implemented. The vehicle is in â€œtag rangeâ€ when it is on itâ€™s side of the field and an enemy vessel is within 3 meters of their vessel. This does not mean they are requesting a tag. It only means they are within range to do so successfully.
    \ref{sec_iled_in_tag_range_param} \\

    \pvar{IN_FLAG_RANGE} Configuration Parameter} &amp; This configuration parameter defines the name of the variable which will publish when the vehicle with the LEDInfoBar is, â€œIN_FLAG_RANGEâ€.
    The vehicle is â€œin the flag zoneâ€ when it is within 10 meters of the enemy flag. 
    This does not mean they are requesting a â€œgrabâ€. It only means they are within range to do so successfully.
    \ref{sec_iled_in_flag_range_param} \\

            
  \end{longtable}
\end{listing}

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

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

\vspace{0.25in}
\begin{listing}{Example configuration of the iLEDInfoBar application}
\label{lst_iled_econfig}
\footnotesize
\begin{verbatim}
1 ============================================================================
2 iLEDInfoBar Example MOOS Configuration
3 ============================================================================
4
5 ProcessConfig = iLEDInfoBar
6 {
7   AppTick    = 6
8   CommsTick  = 6
9   TEAM_COLOR = blue
10  PORT       = /dev/cu.usbmodem4636831
11  BAUDRATE   = 9600
12  // LED vars to register
13  TAGGED        = LED_TAGGED          
14  OUT_OF_BOUNDS = ONFIELD          
15  HAVE_FLAG     = LED_HAVE_FLAG      
16  IN_TAG_RANGE  = CANTAG     
17  IN_FLAG_ZONE  = LED_IN_FLAG_ZONE    
18 
19 }
\end{verbatim}
\normalsize
\end{listing}

%=============================================================
\section{Publications and Subscriptions for iLEDInfoBar}
\index{iLEDInfoBar!Publications and Subscriptions}
\index{Publications and Subscriptions!iLEDInfoBar}
\label{sec_iled_interface}

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

The \app{iLEDInfoBar} doesn't publish any variables.

%------------------------------------------------------------------
\subsection{Variables Subscribed for by iLEDInfoBar}
\label{sec_iled_subs}

\begin{packed_itemize}[5]
  
\item \mvar{LED\_TAGGED}: TRUE or FALSE     
\item \mvar{ONFIELD}: TRUE or FALSE        
\item \mvar{LED\_HAVE\_FLAG}: TRUE or FALSE  
\item \mvar{CANTAG}: TRUE or FALSE 
\item \mvar{LED\_IN\_FLAG\_ZONE}: TRUE or FALSE
 
\end{packed_itemize}

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

The \app{iLEDInfoBar} application produces some useful information to
the terminal on every iteration of the application. An example is
shown in Listing \ref{lst_iled_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{iLEDInfoBar}}
\label{lst_iled_appcast}
\footnotesize
\begin{verbatim}
1 ===================================================================
2 iLEDInfoBar alpha 0/0(442)
3 ===================================================================
4 ==========================================                                      
5 ICON STATES                                                                
6   [0]= off [1]= active [2]= blinking                                       
7 ==========================================                                  
8     LED_TAGGED     [0]
9   ON_FIELD     [0]
10  LED_HAVE_FLAG  [0]
11  CAN_TAG    [0]
12  LED_IN_FLAG_ZONE   [0]
13 
14
15
16
17 ==========================================                                      
18 Most Recent Events (1):                                       
19 ==========================================                                  
20 Serial port is open
21 Serial port opened. Communicating over port /dev/ttyAMC0
22
23
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
Lines 8-12 show the state of each icon.
Lines 20-21 show recent events. During a game it will publish its mail as it comes, in the same area.

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

\emph{Appcasting}:
â€œSerial port is NOT openâ€ 
check the moos file with the iLEDInfoBar config block and make sure the correct serial port is listed.

\begin{verbatim}
â€œSerial port opened. Communicating over port /dev/ttyAMC0â€ 
\end{verbatim}
And the LED bar isnâ€™t responding 

\emph{Using the command line for debugging}:
To confirm that the serial port listed is for the LED Bar, go to the command line and send a command to that serial port:

\begin{verbatim} $ echo 81 &gt; /dev/ttyAMC0 # this will turn all the light ON \end{verbatim}

if that turns the lights on, then to turn them off:

\begin{verbatim} $ echo 80 &gt; /dev/ttyAMC0 # this will turn all the light OFF \end{verbatim}

if that doesnâ€™t turn the lights on, either the LED Bar isnâ€™t connected to a power source, the power source isnâ€™t giving it enough power, the serial port is incorrect OR there may be a problem with the soldering on the LED strip. However, triage any issues before resorting to surgery. 

\emph{If it turns the LEDs on BUT on the first one or two, there is a fault somewhere between the lit LED and the off LED.}

\emph{Not receiving mail}:
If you are not seeing any mail in the appcasting window of the vehicle, and the LED bar hardware is working, confirm the variables iLEDInfoBar is registering for are being bridged properly from shoreside. Find the list of bridged variables in the uFldShoreBroker config block in the shoreside moos file.

\vspace{0.1in}
\begin{listing}{Example config block: \app{uFldShoreBroker}}
\label{lst_iled_appcast}
\footnotesize
\begin{verbatim}
1 =======================================================================
2 uFldShoreBroker config for iLEDInfoBar Example
3 =======================================================================
4
5 ProcessConfig = uFldShoreBroker
6 {
7   AppTick    = 6
8   CommsTick  = 6
9     
10  qbridge  = LED_TAGGED, LED_HAS_FLAG, ONFIELD, CANTAG, LED_IN_FLAG_ZONE
12
13}
14
\end{verbatim}

If the \app{uFldShoreBroker} is properly configured but youâ€™re still not getting mail, look in the \app{uFldTagManager} and \app{uFldFlagManager} config blocks in the shoreside moos file. They must have all the vars listed in the \app{uFldShoreBroker} config block (relevant to the LED bar.)

\vspace{0.1in}
\begin{listing}{Example config block: \app{uFldFlagManager}}
\label{lst_iled_appcast}
\footnotesize
\begin{verbatim}
1 =======================================================================
2 uFldFlagManager config for iLEDInfoBar Example
3 =======================================================================
4
5 ProcessConfig = uFldFlagManager
6 {
7   AppTick    = 2
8   CommsTick  = 2
9     
10  â€¦
12
13  grab_post = var=LED_HAVE_FLAG_$UP_VNAME, sval={true}
14
15  â€¦
16 
17  lose_post = var=LED_HAVE_FLAG_$UP_VNAME, sval={false}
18
19  â€¦
20
21  near_post = var=LED_IN_FLAG_ZONE_$VNAME, sval={true}  
22
23  â€¦
24
25  away_post = var=LED_IN_FLAG_ZONE_$VNAME, sval={false}
26
27  â€¦ 
28
29  home_post = var=LED_HAVE_FLAG_$UP_VNAME, sval={false}
30
31  â€¦
32  
33  goal_post = var=LED_HAVE_FLAG_$UP_VNAME, sval={false}
34
35 }
\end{verbatim}

\vspace{0.1in}
\begin{listing}{Example config block: \app{uFldTagManager}}
\label{lst_iled_appcast}
\footnotesize
\begin{verbatim}
1 =======================================================================
2 uFldTagManager config for iLEDInfoBar Example
3 =======================================================================
4
5 ProcessConfig = uFldTagManager
6 {
7   AppTick    = 2
8   CommsTick  = 2
9     
10  â€¦
12
13  robot_tag_post   = LED_TAGGED_$UP_TARGET=true
14  human_tag_post   = LED_TAGGED_$UP_TARGET=true
15
16  â€¦
17
18  human_untag_post = LED_TAGGED_$UP_TARGET=false
19
20  â€¦
21
22  robot_untag_post = LED_TAGGED_$UP_TARGET=false
23
24 
25 } 
\end{verbatim}



\end{document}

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