<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{iJoyStick: Interfacing MOOS with Joystick Devices}
\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, CSAIL}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=PavLab.IJoyStick}
\wikidoc{bugz=iJoyStick}
\wikidoc{auth=ayaari@mit.edu}


%====================================================================
\section{iJoystick: Interfacing MOOS with Joystick Devices}
%====================================================================
\label{sec_iJoystick}
\index{iJoystick}

The purpose of the \app{iJoystick} application is to interface with
controller hardware then publish axis and button values to a MOOS
community. Following the guideline \textquotedblleft One purpose, one
MOOS app,\textquotedblright publications are raw axis position values
and button statuses. The companion application \app{pMapValues} is
used to map joystick axis and button values from the raw source
messages into actionable MOOS messages.

These applications were written to work together for joystick command
of a vehicle. Yet, each of these applications is written to act as a
generic independent service. The joystick interface can be used to
provide manual inputs to any subsystem, such as vehicle control, winch
movement, or even just as simple trigger buttons beyond the
\app{pMarineViewer} interface. The mapper can consume any data from
ranged variables or trigger values from another source.


%====================================================================
\subsection{Building the iJoystick Application}
\label{subsec_building_iJoystick}

The \app{iJoystick} application is dependent on the Simple Directmedia
Layer 2.0 (SDL2) library, distributed under a zlib license. More
information about SDL2 is available on their project page
\urlx{http://libsdl.org}.

Prior to building, the SDL2 library must be installed on the
computer. Installation instructions for various platforms can be found
on the SDL2 web site \urlx{http://wiki.libsdl.org/Installation}.

\paragraph{Mac OS X}
The official install web site describes how to build SDL2 from
scratch. MacPort users can install with the following command: 

\vspace{0.1in}
\begin{consoleverb}
  $ sudo port install libsdl2   
\end{consoleverb}

\paragraph{GNU/Linux}
In many cases, GNU/Linux will already have SDL2 installed. On an
Ubuntu system, the library can be verified or installed with the
command:

\vspace{0.1in}
\begin{consoleverb}
$ sudo apt-get install libsdl2-dev
\end{consoleverb}

%====================================================================
\subsection{Using the iJoystick Application}
\label{subsec_using_iJoystick}

Any standard joystick that can be polled by the operating system can
be used with \app{iJoystick}. Generally, a controller consists of
multiple axes buttons for human interface. On a given computer, one or
more joysticks may be connected.

%====================================================================
\subsection{Connecting Multiple Devices}
\label{subsec_multiple}

Considering that one, many, or no controllers may be connected to the
computer, the application will select the relevant joystick on startup
as follows:

\vspace{0.15in}
\begin{tabular}{| c l |}
  \hline
      {\bf Count} &amp; {\bf Joystick Selection} \\
      \hline
      0  &amp; No suitable controllers are available so no output will be created. \\
      1  &amp; The one available controller will be used as the input device. \\
      &gt;1 &amp; The \pvar{ID\_by\_button} parameter selects which device to connect with. \\
      \hline
\end{tabular}
\vspace{0.15in}

\noindent
One instance of \app{iJoystick} can connect with only one joystick. If
the MOOS community calls for more than one controller unit,
\app{iJoystick} can be invoked more than once, with the mission file
parameter \pvar{ID\_by\_button} to assist the human user with
identifying the correct device. The parameter describes an ID of a
button on the controller. When launched, \app{iJoystick} will
continuously poll all controllers until the specified button is
pressed. At that time, normal output will commence.

It is possible that the output of multiple \app{iJoystick} will
interfere with each other. The \pvar{output\_prefix} parameter solves
this issue by allowing each instance to publish unique message names.

%====================================================================
\subsection{Buttons}
\label{subsec_buttons}

A controller can have zero to many buttons. A button is defined as a
single device that provides a binary report of its
position. Generally, physical controllers are designed so that
momentary buttons rest in the unpressed state (\var{UP}) and require a
person to physically hold them to maintain a pressed state
({\var{DOWN}).

Button states are initially published on startup when the controller
is connected. Update messages are subsequently reported only when the
button state changes, i.e., on press or release. Publications are the
string values \var{UP} or \var{DOWN}.

%====================================================================
\subsection{Axes}
\label{subsec_axes}
A joystick controller can have zero to many axes. An axis is defined
as a single human-operable input channel capable of reporting its
position along a continuous range. On the physical device, an axis can
be the X or Y throw of a stick, the rotation of a paddle or steering
wheel, the distance a foot pedal is depressed, or many other
possibilities. Axis values are reported continuously at the
\var{appTick} rate set in the mission file.

\subsubsection{Axis Ranges}
\label{subsubsec_axis_ranges}
\app{iJoystick} publishes axis values in the range $[-32768,
  32768]$. Depending on the manufacturer's intended use of the
physical device, axes are either self-homing or they retain
position. Typically, interfaces such as sticks, steering wheels, and
twist inputs return to the center home position that corresponds to a
zero value. Continuous-range buttons and pedals return to home at one
end of travel and usually report the minimum value. Non-homing sticks
and paddles remain in place even when the user lets go, continuing to
report the same value.
\noindent

%===================================================================
\subsection{The XBox 360 Controller}
\label{subsec_Xbox360}
The XBox 360 controller is commonly available and includes a
convenient number of axis and button inputs. This device works
natively under Windows and Linux. Third-party drivers are required for
Mac OS X. The \mvar{360Controller} project is distributed with the GNU
General Public License from
\urlx{http://github.com/360Controller/360Controller}.


\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/XBox360Controller.png}
  \caption{The XBox 360 Controller}
  \label{fig_joystickAxis}
\end{figure}
\vspace{0.1in}

\vspace{0.15in}
\begin{tabular}{| c l |}
  \hline
      {\bf Button ID} &amp; {\bf Location on controller} \\
      \hline
      $0$ &amp; Green \mvar{A} button \\
      $1$ &amp; Red \mvar{B} button \\
      $2$ &amp; Blue \mvar{X} button \\
      $3$ &amp; Amber \mvar{Y} button \\
      $4$ &amp; Left index finger press \\
      $5$ &amp; Right index finger press \\
      $6$ &amp; Left joystick, press down \\
      $7$ &amp; Right joystick, press down \\
      $8$ &amp; \mvar{START} button (right side of silver \mvar{X} button) \\
      $9$ &amp; \mvar{BACK} button (left side of silver \mvar{X} button) \\
      $10$ &amp; Silver \mvar{X} button \\
      $11$ &amp; Joy-pad up \\
      $12$ &amp; Joy-pad down \\
      $13$ &amp; Joy-pad left \\
      $14$ &amp; Joy-pad right \\
      \hline
\end{tabular}
\vspace{0.15in}

\vspace{0.15in}
\begin{tabular}{| c l |}
  \hline
      {\bf Axis ID} &amp; {\bf Location on controller} \\
      \hline
      $0$ &amp; Left joystick, horizontal motion (dependent on axis 1) \\
      $1$ &amp; Left joystick, vertical motion (dependent on axis 0) \\
      $2$ &amp; Left index finger press (under button 4) \\
      $3$ &amp; Right joystick, horizontal motion (dependent on axis 1) \\
      $4$ &amp; Right joystick, vertical motion (dependent on axis 0) \\
      $5$ &amp; Right index finger press (under button 5) \\
      \hline
\end{tabular}
\vspace{0.15in}

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

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

\vspace{0.15in}
\begin{listing}{Configuration Parameters for iJoystick}
  \label{lst_phi_params}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.76\textwidth}} 
    
    \pvar{output\_prefix}: &amp; (string, default =
    \var{JOY\_}) The message names for published axis and
    button values will begin with this string. \\
    
    \pvar{id\_by\_button}: &amp; (integer, default = $0$) Only relevant
    when more than one controller is attached, ignored otherwise. The
    ID number of the button that will uniquely identify the relevant
    controller. After launch, \app{iJoystick} waits for the specified
    button to be pressed for identification. \\
    
    \pvar{dependent}: &amp; (pair of comma-separated integers) Some
    joysticks, such as the XBox 360 Controller, have a physical
    dependency between the two axes sharing a stick. When this
    parameter is specified, \app{iJoystick} will publish a second
    message for each axis with suffix \var{\_DEP} containing a
    comma-separated value pair of the axis value and its dependent. \\
  \end{longtable}
\end{listing}


%====================================================================
\subsubsection*{An Example MOOS Configuration Block}

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

\vspace{0.1in}
\begin{consoleverb}
$ iJoystick --example or -e
\end{consoleverb}
\vspace{0.1in}
	
\vspace{0.25in}
\begin{listing}{Example configuration of the iJoystick application}
\label{lst_iJoystick_econfig}
\footnotesize
\begin{verbatim}
1   ============================================================================
2   iJoystick Example MOOS Configuration
3   ============================================================================
4
5   ProcessConfig = iJoystick
6   {
7       AppTick    = 10
8       CommsTick  = 10
9
10      ID_by_bytton  = 0     // If more than one joystick is connected, this is the
11                            //   0-based button ID of the joystick that identifies
12                            //   the controller to interface with.
13      Output_Prefix = JOY_  // All output for this joystick will be published
14                            //   with this prefix on the message names.
15                            //   Default is JOY_
16      Dependent     = 0,1   // For joysticks that output axes based on circular
17                            //   distance, this relates to two axes. Order is
18                            //   not important. If defined, axes will publish a
19                            //   second message including values for both axes.
20  }                                                              
\end{verbatim}
\normalsize
\end{listing}

%=============================================================
\subsection{Publications and Subscriptions for iJoystick}
\index{iJoystick!Publications and Subscriptions}
\index{Publications and Subscriptions!iJoystick}
\label{sec_ijoystick_interface}

The interface for \app{iJoystick}, 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}
$ iJoystick --interface or -i
\end{consoleverb}
\vspace{0.05in}
                             
%---------------------------------------------------------------------
\subsubsection{Variables Published by iJoystick}
\label{sec_iJoystick_pubs}

The primary output messages of \app{iJoystick} are axis values, button
statuses, and appcasting reports. The prefix for axis and button
messages is set in the \pvar{output\_prefix} mission file parameter.

\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{[output\_prefix]\_axis[number]}: (double) Current position
  of the joystick axis referenced by [number] as a numerical value in
  the range $[-32768, 32768]$, representing end-to-end travel of the
  axis.
	
\item \mvar{[output\_prefix]\_button[number]\_dep}: (string) Current
  position of the joystick axis referenced by [number] and the current
  value for the dependent axis. Format is \var{axis, dependent-axis}.
	
\item \mvar{[output\_prefix]\_button[number]}: New status of the
  joystick button referenced by [number]. Message content can be
  either \var{UP} or \var{DOWN}.
	
\end{packed_itemize}

%------------------------------------------------------------------
\subsubsection{Variables Subscribed for by iJoystick}
\label{sec_iJoystick_subs}

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