\documentclass[12pt]{article}

\usepackage{setspace}
\usepackage[letterpaper,top=1in,bottom=1in,left=1.25in,right=1.25in]{geometry}

\pagestyle{empty}

\newcommand{\upline}{\vspace*{-\baselineskip}}
\newcommand{\downline}{\vspace*{\baselineskip}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\singlespace
\centerline{\bf iModemSim Operation Handbook}
\downline

iModemSim was designed and built over a short period of time in March, 2008
to allow the simulated testing of MLBL algorithms that required a 
MicroModem compatible system to ensure that the delays would not cause
algorithm failure.

\section*{Overall design}
The main modem simulator module is loosely coupled to a MOOS interface,
allowing simple repurposing of the module to other simulator systems as
needed.

The only inputs needed for the modem simulator core are an IP port, a static
or dynamic location (and updates), and a serial port to connect to, to which
it would look like a MicroModem.

The design of the communication backend (between multiple iModemSim processes)
allows all of the processes running on a local network subnet to talk with each
other (UDP broadcasts) as well as with multiple processes on a single machne
(internal TCP server), with no configuration needed beyond the port number
and network broadcast address.

\section*{Usage manual}
\subsection*{Command line}

iModemSim is a standard MOOS application, it can be started in the same ways
as most other MOOS applications:
\begin{itemize}
	\item {\tt iModemSim your\_moos\_file\_here.moos}
\end{itemize}

If you want to run iModemSim and not use a physical serial port, you can
use the companion program {\tt serial\_loopback} to do so (run as root):
\begin{itemize}
	\item {\tt serial\_loopback /dev/ttyLOOPA1 /dev/ttyLOOPA2}
\end{itemize}
This will create the {\tt /dev/ttyLOOPA1} and {\tt /dev/ttyLOOPA2} as UNIX
pseudo-terminal devices (which have an identical interface as a real serial
port) and establish a virtual loopback connection between the two. iModemSim
would be configured to use one of the "serial" ports, and iMicroModem (or
similar) would be configured to use the other.

\subsection*{MOOS mission configuration block}
There are a number of configuration variables, many of which need to be set,
and they are described below.

\begin{itemize}
	\item {\tt AppTick}, {\tt CommsTick} - The standard MOOS main loop variables, the defaults of 4 and 4 work reasonably well, although setting it to at least the value (in Hz) of position updates in the system is a good idea
	\item {\tt Port} - The serial port to connect the simulated modem to (can be a virtual serial port, see above)
	\item {\tt Speed} - The speed to configure the serial port to (modem is generally at 19200)
	\item {\tt DefConf} - Default configurations for the modem; the format is {\tt VAR,<int>}. There can be multiple lines of this type. Some useful ones:
	\begin{itemize}
		\item {\tt SRC} - Modem source ID (i.e {\tt DefConf = SRC,1})
		\item {\tt TOA} - Modem will show time-of-arrival information ({\tt \$CATOA}), set to 1 to enable, 0 to disable
		\item {\tt SNV} - Modem will only transmit on (simulated) sync pulse, used in conjunction with {\tt TOA} to allow testing of one-way-range algorithms.
	\end{itemize}
	\item {\tt IPPort} - The port number that iModemSims will use to communicate amongst themselves.
	\item {\tt BroadcastAddr} - The broadcast address that iModemSim will transmit packets to; what this should be set to depends on the {\tt Bcast} address of the interface you want to transmit the packets on. For example, if all of your computers are on a network {\tt 192.168.0.0-254}, then you would set this to {\tt 192.168.0.255}. If you want to send the broadcast packets to the interface with the default route (internet), you can set it to {\tt 255.255.255.255}; note that these packets will not leave your local subnet.
	\item {\tt InputLocType} - How iModemSim knows where the modem "is"; this can be set to one of a number of settings, with correspondingly dependant configuration values.
	If it's set to:
	\begin{itemize}
		\item {\tt global} - Globally referenced input location that is dynamic, i.e. input variables are doubles of latitude, longitude. In this mode, these variables also need to be set:
		\begin{itemize}
			\item {\tt InputLocLat} - The name of the variable that contains the latitude (for instance, {\tt GPS\_LATITUDE}).
			\item {\tt InputLocLon} - The name of the variable that contains the longitude (for instance, {\tt GPS\_LONGITUDE}).
			\item {\tt InputDepth} - The name of the variable that contains the depth (for instance, {\tt NAV\_DEPTH}). Note that all three of these variables need to be updated at least once after iModemSim starts.
		\end{itemize}
		\item {\tt constant\_global} - Globally referenced input location that is static, i.e. a modem on a simulated dock. In this mode, these variables also need to be set:
		\begin{itemize}
			\item {\tt ConstantPosLat} - A double that contains the constant latitude assigned to this modem (for instance, {\tt 42.3584}).
			\item {\tt ConstantPosLon} - A double that contains the constant longitude assigned to this modem (for instance, {\tt -71.08745}).
			\item {\tt ConstantDepth} - A double that contains the constant depth assigned to this modem (for instance, {\tt 0.0}).
		\end{itemize}
		\item {\tt local} - Locally referenced input location that is dynamic, i.e. a modem running with iKayakSim (for example). In this mode, these variables also need to be set:
		\begin{itemize}
			\item {\tt InputLocX} - The name of the variable that contains the local X position (for instance, {\tt NAV\_X}).
			\item {\tt InputLocY} - The name of the variable that contains the local Y position (for instance, {\tt NAV\_Y}).
			\item {\tt InputDepth} - The name of the variable that contains the local depth (for instance, {\tt NAV\_DEPTH}). Note that all of these variables need to be set in the database at least once after iModemSim is started.
		\end{itemize}
		\item {\tt constant\_local} - Locally referenced input location that is static, i.e. a modem at the LatOrigin/LonOrigin. In this mode, these variables also need to be set:
		\begin{itemize}
			\item {\tt ConstantPosX} - A double that contains the constant X location assigned to the modem.
			\item {\tt ConstantPosY} - A double that contains the constant Y location assigned to the modem.
			\item {\tt ConstantDepth} - A double that contains the constant depth assigned to the modem.
		\end{itemize}
	\end{itemize}
\end{itemize}

Note that in both local modes, the Origin ({\tt LatOrigin} and {\tt LongOrigin})
need to be set in the top level of the mission file.

\end{document}
