\subsubsection{Overview}
Any terms in \textit{italics} are defined the Glossary (section \ref{sec:glossary}).

\begin{figure}[tp]
  \centering 
  \includegraphics[scale=1]{figures/pAcommsHandler_scope.eps}
\caption{pAcommsHandler running with {\tt verbosity = scope}. \label{fig:scope}}
\end{figure}

\paragraph{Problem}
Acoustic communications (in our case, with the WHOI Micro-Modem) are highly limited in throughput. Thus, it is unreasonable to expect ``total throughput'' of all communications data. Furthermore, even if total throughput is achievable over time, certain messages have a lower tolerance for delay (e.g. vehicle status) than others (e.g. CTD sample data). Reference  \url{http://acomms.whoi.edu/umodem/documentation.html} for more information on the WHOI Micro-Modem.

Also, in order to make the best use of this available bandwidth, messages need to be compacted to a minimal size before sending (effective encoding). To do this, pAcommsHandler provides an interface to the Dynamic Compact Control Language (DCCL\footnote{the name comes from the original CCL written by Roger Stokey for the REMUS AUVs, but with the ability to dynamically reconfigure messages based on mission need. DCCL is backwards compatible with a CCL network as it uses CCL message number 32}.) encoder/decoder. Furthermore, DCCL has powerful parsing abilities (``algorithms'') for both encoding and decoding, including the ability to perform certain geodesic conversions (e.g. latitude, longitude $\leftrightarrow$ UTM x,y) and lookups (e.g. \textit{modem\_id} $\leftrightarrow$ vehicle name) on data.

pAcommsHandler roughly performs the same functions of pFramer, pRouter, pAcommsPoller, and iMicroModem but
generalized to handle any number of message queues and extended to give more control over queue parameters. The DCCL encoding is much more flexible and more compact than the CCL encoding used by these older processes.

\paragraph{Solution}
pAcommsHandler provides a(n):
\begin{enumerate}
\item Encoder/decoder unit (codec): encodes and decodes messages using DCCL (goby-acomms {\tt dccl} library), which reduces the data required to be sent by:
\begin{itemize}
\item Predefined messages: the user must specify a message structure what specifies what fields the message contains and how large each field should be (in an intuitive fashion that DCCL turns into bits). Both the sender and receiver have preshared knowledge of the message structure. From this knowledge, no meta information about the message (beyond an identifier) needs to be sent, simply the data. 
\item Custom field sizes: message fields are defined with custom tolerances (ranges and precisions) that are tighter than those given by the IEEE standards for floating point and integer numbers. For example, if a field needs to hold an integer that will never range outside [0, 1000] that field in the message will only be 10 bits long (ceil($\log_2{1001}$)).
\end{itemize}
\item Priority Queuing System: maintains an arbitrary number of message queues (each tied to a different MOOS variable) for hexadecimal data strings. (goby-acomms {\tt queue} library)
\begin{itemize} 
\item allows configuration of the queue priorities and dynamic growth of the priority over the time since the last sent message.
\item allows management of WHOI CCL message types as well as DCCL queuing. 
\end{itemize}
\item Modem Driver: handles all Micro-Modem serial communications. The driver (goby-acomms {\tt modemdriver} library) is intended to be extensible to other modems besides the WHOI Micro-Modem. 
\item MAC Manager: provides medium access control in the form of a simple slotted time division-multiple access (TDMA) scheme or flexible centralized polling.
\end{enumerate}

\paragraph{Limitations}
pAcommsHandler \textit{does not}:

\begin{itemize}
\item provide any multi-hop routing. The sender and receiver must be directly in acoustic communications.
\item split user messages into packets. The user must provide data that are small enough to fit into the modem frame desired (32 - 256 bytes for the WHOI Micro-Modem).
\end{itemize} 

\paragraph{Quick Start}

\subsubsection{Usage}
\paragraph{Compilation}
pAcommsHandler depends on the boost, boost\_thread, boost\_date\_time, boost\_regex, xerces-c, crypto++, and asio libraries in addition to the libraries included in MOOS and moos-ivp-local.

\begin{itemize}
\item boost: reference \url{http://www.boost.org/} or look for your distribution's boost developer package (libboost-dev in Debian/Ubuntu).
\item boost\_thread: reference \url{http://www.boost.org/} or look for your distribution's boost\_thread developer package (libboost-thread-dev in Debian/Ubuntu).
\item boost\_date\_time: reference \url{http://www.boost.org/} or look for your distribution's boost\_date\_time developer package (libboost-date-time-dev in Debian/Ubuntu).
\item boost\_regex: reference \url{http://www.boost.org/} or look for your distribution's boost\_regex developer package (libboost-regex-dev in Debian/Ubuntu).
\item asio: reference \url{http://sourceforge.net/projects/asio/} or look for your distribution's asio developer package (libasio-dev in Debian/Ubuntu). You do not want boost-asio, just asio. Note that you will need a fairly recent version of asio, so it may be best to simply install from source. asio is a header-only library so it is simply a matter of copying the header files to /usr/local/include or a similar directory.
\item xerces-c: reference \textit{http://xerces.apache.org/xerces-c/} or look for your distribution's xerces-c developer package (libxerces-c-dev in Debian/Ubuntu as of this writing).
\item crypto++: reference \textit{http://www.cryptopp.com} or look for your distribution's crypto++ developer package (libcrypto++-dev in Debian/Ubuntu as of this writing).
\item ncurses: should be provided with most UNIX systems.
\end{itemize}

\subsubsection{Parameters for the pAcommsHandler Configuration Block}\label{sec:pAcommsHandler:config}
\paragraph{Example moos file}

\begin{tiny}\begin{verbatim}
modem_id = 1    
modem_id_lookup_path = ../../../data/acomms/modemidlookup.txt

log_path = /tmp/moos/logs  // directory to log runtime debugging output to

ProcessConfig = pAcommsHandler
{
  // available to all moos processes.
  AppTick    = 10
  CommsTick  = 10
  
  verbosity = verbose   // scope, verbose [default], terse, quiet
  log = true // true [default] or false

  //////////////////////
  // DCCL Codec configuration
  //////////////////////
  
  // or you could use pGeneralCodec if you set these to "false"
  // default (for legacy support) is false for both
  encode = true // true or false [default]
  decode = true // true or false [default]
  
  crypto_passphrase = my_precious // if omitted, messages are not encrypted

  //////////////////////
  // XML files (used for both Queuing and DCCL encoding)
  //////////////////////
  
  message_file = ../../../data/acomms/acoustic_moospoke.xml

  // manipulators go between "message_file = " and "somexml.xml". comma separate multiple manipulators
  message_file = on_demand = ../../../data/acomms/simple_status.xml
  message_file = loopback,no_queue = ../../../data/acomms/simple_deploy.xml

  // relative to location of xml files! (syntax checking)
  schema = ../../../moos-ivp-local/src/tes/goby/acomms/libdccl/message_schema.xsd


  //////////////////////
  // CCL Queuing configuration (for non-DCCL CCL messages)
  //////////////////////
  
  // send_CCL = outgoing_hex_moos_var,
                             //     id
                             //         ack
                             //             blackout_time
                             //                 max_queue
                             //                      newest_first
                             //                          value_base
                             //                               ttl
  send_CCL    = OUT_REMUS_STATUS_HEX_30B,   0e, 0, 0, 1, 1, 0.8, 1800
  // receive_CCL = incoming_hex_moos_var, id
  receive_CCL = IN_REMUS_STATUS_HEX_30B,    0e
  receive_CCL = IN_REMUS_RANGER_HEX_30B,    10
  send_CCL    = OUT_REMUS_REDIRECT_HEX_30B,   07, 1, 0, 5, 1, 5, 1800
  receive_CCL = IN_REMUS_REDIRECT_HEX_30B,    07

  //////////////////////
  // Driver configuration
  //////////////////////
  connection_type = serial // serial [default], tcp_as_client, tcp_as_server
  serial_port = /dev/ttyS0 
  baud = 19200 // 9600, 19200 [default], 38400, ... must conform to BR1 setting

  // for connection_type = tcp_as_client or tcp_as_server
  // network_port = 10000
  // for connection_type = tcp_as_client
  // network_address = 192.168.1.124

  // set all CFG values to factory defaults at the start before sending our CFG values
  cfg_to_defaults = true // true [default] or false

  // modem CFG values
  cfg = snr,1
  cfg = rev,0
  
  //////////////////////
  // MAC
  //////////////////////
  mac = slotted // or polled, fixed_slotted, or none [default]

  // for slotted
  slot_time = 15 // seconds for the width of each slot, default 15
  rate = 0    // modem rate (0 [default], 2, 3, 5 or auto [not implemented])
  expire_cycles = 30   // how many cycles to go without hearing from a vehicle before removing them

  // for polled
  // initializer.string = ACOMMS_POLLER_UPDATE = destination=1,update_type=add,poll_type1=data,poll_from_id1=1,poll_to_id1=0,poll_rate1=0,poll_wait1=15
  // initializer.string = ACOMMS_POLLER_UPDATE = destination=1,update_type=add,poll_type1=data,poll_from_id1=2,poll_to_id1=0,poll_rate1=0,poll_wait1=15
 
  //////////////////////
  // Misc
  //////////////////////

  // initialize MOOS variable to value of the .moos file variable from the top of the moos file 
  global_initializer.double = LAT_ORIGIN = LatOrigin
  global_initializer.double = LONG_ORIGIN = LongOrigin
  global_initializer.string = MODEM_ID_PATH = modem_id_lookup_path

  // initialize MOOS variable from value set here
  initializer.string = VEHICLE_NAME = unicorn
  initializer.string = VEHICLE_TYPE = auv
}
\end{verbatim}\end{tiny}

\paragraph{Filling out the .moos file}

\paragraph{General Parameters}
\begin{itemize}
\item \texttt{verbosity}: choose \texttt{verbose} for full text terminal output, {\tt terse} for symbolic heartbeat output, and {\tt quiet} for no terminal output. A new \texttt{scope} mode is helpful to debugging and visualizing the many data flows of pAcommsHandler. See figure \ref{fig:scope} for a screenshot of pAcommsHandler in scope mode. 
\item \texttt{modem\_id}: integer that specifies the modem\_id of this current vehicle / community. this must match the micromodem SRC configuration parameter (send the modem \texttt{\$CCCFQ,SRC} to check). For the remainder of the document, \textit{modem\_id} refers to the value \texttt{\$CCCFG,SRC,modem\_id}. If using the internal driver (\texttt{driver\_file = internal}), this configuration parameter will be set on startup. often this is set as a global parameter to the moos file (specifed outside the ProcessConfig blocks).
\item \texttt{modem\_id\_lookup\_path}: path to a text file giving the mapping between {\tt modem\_id} and vehicle name and type for a given experiment. This file should look like:
\begin{small}\begin{verbatim}
// modem id, vehicle name (should be community name), vehicle type, other aliases
0, broadcast, broadcast
1, endeavor, ship
3, unicorn, auv
4, macrura, auv
\end{verbatim}\end{small}
\item \verb|initializer|: since many times it is useful to have a MOOS variable including in a message that remains static for a given mission (vehicle name, etc), we give the option to publish initial MOOS variables here (for later use in messages [until overwritten, of course]).
\item \verb|global_initializer|: looks for a global (i.e. specified at the top of the MOOS file or outside any \verb|ProcessConfig| blocks) value in the .moos file with the name to the right of the colon and publishes it to a MOOS variable with the name to the left of the colon. For example, \verb|global_initializer.double = LAT_ORIGIN = LatOrigin| looks for a variable in the .moos file called \verb|LatOrigin| and publishes it to the MOOSDB as a double variable \verb|LAT_ORIGIN| with the value given by \verb|LatOrigin|.
\item \texttt{log\_path}: folder to log all terminal output to for later debugging. Similar to system logs in /var/log.
\item \texttt{log}: boolean to indicate whether to log terminal output or not.
\end{itemize}

\paragraph{Encoding/Decoding (DCCL) Parameters} \label{dccl_param}
\begin{itemize}
\item \texttt{encode}: boolean flag indicating if pAcommsHandler should encode the messages specified in \texttt{message\_file=}. Alternatively, you can run pGeneralCodec to encode these messages. [optional, default is false for legacy support].
\item \texttt{decode}: boolean flag indicating if pAcommsHandler should decode the messages specified in \texttt{message\_file=}. [optional, default is false for legacy support].
\item \texttt{crypto\_passphrase}: secret text string used to encrypt DCCL messages with. All parties to the communication must have the same passphrase and this must be kept secret for secure communications. [optional, messages will not be encrypted if this is not provided.].
\item \verb|message_file|: path to an XML file containing a message set of one or messages. You can insert manipulators in between the \texttt{message\_file=} and \texttt{somefile.xml} that change the behavior of pAcommsHandler for messages defined in that file. Comma separate multiple manipulators. Allowed manipulators:
\begin{itemize}
\item {\tt no\_encode}: do not encode this message
\item {\tt no\_decode}: do not decode this message
\item {\tt  no\_queue}: do not queue this message
\item {\tt  loopback}: decode this message internally immediately following encode (used to command yourself)
\item {\tt on\_demand}: encode immediately upon a data request command (use for time sensitive messages like STATUS)
\end{itemize}
\item \texttt{schema}: path to the DCCL \texttt{message\_schema.xsd} XML schema used for syntax checking. If using a relative path, specify the path relative to the XML file location, \textit{not} the present working directory (pwd).
\end{itemize}

\paragraph{DCCL Queuing information stored in message XML files} \label{sec:xmlqueue}
All queue configuration for DCCL messges must be configured within the XML files \texttt{<queuing />} tag and included with \texttt{message\_file = message.xml}. The tags correspond to these configuration variables:

\begin{itemize}
\item \texttt{outgoing\_hex\_moos\_var}: name of the moos variable to subscribe to for
  messages to add to this queue. Publishes here should be pure
  hexadecimal or a key=value string specified later in section
  \ref{inputformat}.
\item \texttt{id}: a user specified integer from 0-127 that is a
  tag for the \texttt{outgoing\_hex\_moos\_var}. Thus, each \texttt{outgoing\_hex\_moos\_var} must have a unique
  \texttt{id}. Only the \texttt{id} is sent with the
  message (to save space), not the full \texttt{outgoing\_hex\_moos\_var} of the
  queue. Thus, this must match the \texttt{id} on the receiving
  vehicle's \texttt{receive} configuration in the incoming parameters
  section below. For example, if i have \texttt{send=SOME\_OUT\_HEX, 1} on
  the sending vehicle, the receiving vehicles must have a field
  \texttt{receive=SOME\_IN\_HEX, 1}. All messages with ID 1 will be put in
  \texttt{SOME\_IN\_HEX}. Clearly, if unique mapping is desired on the
  receiving end, unique \texttt{id}s must be used on the sending
  end.
\item \texttt{ack}: boolean flag (1=true, 0=false) whether to request an
  acoustic acknowledgment on all sent messages from this field. If
  omitted, default of 0 (false, no ack) is used.
\item \texttt{blackout\_time}: time in seconds after sending a message
  from this queue for which no more messages will be sent. Use this
  field to stop an always full queue from hogging the channel. If
  omitted, default of 0 (no blackout) is used.
\item \texttt{max\_queue}: number of messages allowed in the queue before
  discarding messages. If \texttt{newest\_first} is set to true, the
  oldest message in the queue is discarded to make room for the new
  message. Otherwise, any new messages are disregarded until the space
  in the queue opens up.
\item \texttt{newest\_first}: boolean flag (1=true=FILO, 0=false=FIFO)
  whether to send newest messages in the queue first (FILO) or not
  (FIFO).
\item \texttt{ttl}: the time (in seconds) the message is allowed to live before being discarded. This also factors into the priority calculation as messages with a lower time-to-live (ttl) grow in priority faster. 
\item \texttt{value\_base}: 
Each queue has a base value ($V_{base}$) and a time-to-live ($ttl$) that create the priority ($P(t)$) at any given time ($t$):
 \[
P(t) = V_{base} \frac{(t-t_{last})}{ttl}
 \]
 where $t_{last}$ is the time of the last send from this queue.

This means for every queue, the user has control over two variables ($V_{base}$ and $ttl$). $V_{base}$ is intended to capture how important the message type is in general. Higher base values mean the message is of higher importance. The $ttl$ governs the number of seconds the message lives from creation until it is destroyed by libqueue. The $ttl$ also factors into the priority calculation since all things being equal (same $V_{base}$), it is preferable to send more time sensitive messages first. So in these two parameters, the user can capture both overall value (i.e. $V_{base}$) and latency tolerance ($ttl$) of the message queue.

\end{itemize}

An example queuing block:
\begin{small}\begin{verbatim}
<message_set>
  <message>
    <id>23</id>
    ...
    <queuing>
      <ack>false</ack>
      <blackout_time>0</blackout_time>
      <max_queue>1</max_queue>
      <newest_first>true</newest_first>
      <value_base>4</value_base>
      <ttl>1000</ttl>
    </queuing>
  </message>
  ...
</message_set>
\end{verbatim}\end{small}

\paragraph{CCL Queue Parameters}
\begin{itemize}
\item \texttt{send\_CCL}: configure a queue for a WHOI CCL message type
  (do not use the moos \texttt{id}). The queues mentioned above
  (\texttt{send=}) use the CCL identifier byte 0x20 and then the second
  byte includes the \texttt{VariableID} leaving $N-2$ bytes for the user
  where $N=32, 64, \hbox{ or } 256$ depending on the modem rate. This
  queue \texttt{send\_CCL} does not use the second byte, thus making it
  useful for handling the static CCL types defined by WHOI. The send\_CCL parameter is a comma delimited string of two
  mandatory parameters and up to six optional parameters (in order
  specified here). To skip an optional field and use the default
  value, simply use a blank ",":  
  All parameters in the \texttt{send\_CCL} list are the same as those for the
  DCCL tag list with the exception of the second parameter. Here it
  is the \texttt{CCLIdentifierByte} in hexadecimal, not the \texttt{id}.
\item \texttt{receive\_CCL}: specifies a mapping between an incoming
  \texttt{incoming\_hex\_moos\_var} and a moos variable to place the incoming
  message. The sender's modem id is stored as the community name for
  the received message. Rather than a \texttt{incoming\_hex\_moos\_var} you specify a
  \texttt{CCLIdentifierByte} that is the first byte of the CCL message.
\end{itemize}

\paragraph{Micro-Modem Driver Parameters}
\begin{itemize}
\item \texttt{connection\_type}: type of connection to make to the modem (serial, tcp\_as\_client, tcp\_as\_server) [optional, default: serial]
\item \texttt{serial\_port}: serial port to which the MicroModem is connected [mandatory if \texttt{connection\_type=serial}].
\item \texttt{baud}: baud rate to use. [optional, default: 19200]
\item \texttt{network\_port}: networking port to use. [mandatory if \texttt{connection\_type=tcp\_*}]
\item \texttt{network\_port}: IPv4 networking address of the server to connect to. [mandatory if \\ \texttt{connection\_type=tcp\_as\_client}]
\item \texttt{cfg}: set some modem NVRAM setting to a value. note that by default pAcommsHandler resets all NVRAM (CFG) parameters on startup (\texttt{\$CCCFG,ALL,0}) and then sets the these values. thus, you must include \texttt{cfg=} lines only for parameters that differ from the defaults. Set \texttt{cfg\_to\_defaults=false} to turn off the automatic reset of the CFG parameters. 
\end{itemize} 

\paragraph{Medium Access Control (MAC) Parameters}
\begin{itemize}
\item \texttt{mac}: type of Medium Access Control. Values can be \texttt{slotted}, \texttt{polled}, \texttt{fixed\_slotted} or \texttt{none}.
\item \texttt{slot\_time}: length, in seconds, of each communication slot for the \texttt{mac=slotted} MAC option.
\item \texttt{rate}: rate for the \texttt{mac=slotted} MAC option. 0 is a single 32 byte packet (FSK), 2 is three frames of 64 bytes (PSK), 3 is two frames of 256 bytes (PSK), and 5 is eight frames of 256 bytes (PSK)
\item \texttt{initializer.string}: use the MOOS variable \texttt{ACOMMS\_MAC\_CYCLE\_UPDATE} to adjust the TDMA schedule for the  \texttt{mac=polled} or \texttt{mac=fixed\_slotted} MAC option. To set a few initial values, you can use the \texttt{initializer} key to ``poke'' this MOOS variable on startup. The format of \texttt{ACOMMS\_MAC\_CYCLE\_UPDATE} is a string of comma delimited \texttt{key=value} pairs, where \# is an incrementing number for each slot specified in the message. See table \ref{tab:pAcommsHandler:poll} for all the keys and values.

\begin{table}
\centering
\footnotesize
\begin{tabular}{|c|c|c|}
\hline key & value \\ \hline
\hline destination & modem\_id of poller to update  \\ 
\hline update\_type & enum\{add,replace,remove\}  \\ 
\hline slot\_\#\_type & enum\{data,ping\} \\ 
\hline slot\_\#\_from & modem\_id of the sender  \\ 
\hline slot\_\#\_to & modem\_id of the receiver  \\ 
\hline slot\_\#\_rate & rate to poll at  \\ 
\hline slot\_\#\_wait & seconds for the slot to last before next poll \\ 
\hline 
\end{tabular} 
\caption{Parameters of \texttt{mac=polled} and \texttt{mac=fixed\_slotted} reconfiguration message (to \texttt{ACOMMS\_MAC\_CYCLE\_UPDATE})} \label{tab:pAcommsHandler:poll}
\end{table}

for example:
\begin{small}\begin{verbatim}
destination=1,update_type=add,slot_1_type=data,slot_1_from=1,slot_1_to=0,
slot_1_rate=0,slot_1_wait=15
\end{verbatim}\end{small}

\end{itemize} 

\subsubsection{MOOS variables subscribed to by pAcommsHandler}
\begin{table}
\centering
\footnotesize
\begin{tabular}{|p{0.3\textwidth}|c|p{0.4\textwidth}|p{0.15\textwidth}|}
\hline MOOS variable or .moos file key or XML tag specifying a MOOS variable & Type & Description
& Published by \\  \hline\hline
\textbf{DCCL} &&& \\ \hline\hline
$<$destination\_moos\_var key="destkey"/$>$ & \$ or D & Contains the modem\_id to send this message from. Can either be double (ex: 3) or string (ex: ...,destkey=3,...) & many \\ \hline
$<$trigger\_moos\_var/$>$ & \$ or D & A publish here triggers the creation of this message. The contents may contain message parts or not. & many \\ \hline
$<$moos\_var key="somekey"/$>$ & \$ or D & Data for a given \textit{message\_var}. Can either be double (ex: 3.234) or string (ex: ``bob'' or ``3.234'') or keyed string (ex: ...,somekey=3.234,...). & many \\ \hline
\hline \textbf{Queue} &&& \\ \hline\hline
send= &&&\\  outgoing\_hex\_moos\_var,... & \$ & outgoing\_hex\_moos\_var contains
hexadecimal string to queue (and eventually send). & Various Codecs
(pCTDCodec, pBTRCodec, etc.)\\ \hline
$<$outgoing\_hex\_moos\_var/$>$ & \$ & outgoing\_hex\_moos\_var contains
hexadecimal string to queue (and eventually send). \textbf{Only subscribed for when DCCL encoding is disabled in pAcommsHandler.} & pGeneralCodec \\ \hline
\hline \textbf{Driver} &&& \\ \hline\hline
ACOMMS\_NMEA\_OUT & \$ & Raw messages to send to the modem & \\ \hline
\hline \textbf{MAC} &&& \\ \hline\hline
ACOMMS\_MAC\_CYCLE\_UPDATE & \$ & Updates to the mac=polled or mac=fixed\_slotted TDMA cycle &  \\ \hline
 \end{tabular}
 \caption{MOOS Variables Subscribed to by pAcommsHandler} \label{tab:pAcommsHandler:subscribe}
\end{table}

Some variables are configurable in the .moos file and/or message XML files as described in
section \ref{sec:pAcommsHandler:config}. For example, if
\texttt{ send = OUT\_CTD\_HEX\_30B, ...} is set in the .moos file (or \\ \texttt{<outgoing\_hex\_moos\_var>OUT\_CTD\_HEX\_30B</outgoing\_hex\_moos\_var>} in a message XML file), then
\texttt{OUT\_CTD\_HEX\_30B} is the variable actually subscribed. See section \ref{sec:ex_xml} and beyond for details on filling out and interpreting these XML files. See table \ref{tab:pAcommsHandler:subscribe} for a full list of the subscribed variables.

\subsubsection{MOOS variables published by pAcommsHandler}

\begin{table}
\centering
\footnotesize
\begin{tabular}{|p{0.25\textwidth}|c|p{0.4\textwidth}|p{0.2\textwidth}|}
\hline MOOS variable or .moos file key or XML tag specifying a MOOS variable & Type & Description & Format \\ \hline 
\hline \textbf{DCCL} &&& \\ \hline\hline
$<$publish$>$ $<$moos\_var type="string"/$>$ $<$/publish$>$& \$ & (string) Message created from decoded hexadecimal string. & Defined by \xmltag{format} \\ \hline
$<$publish$>$ $<$moos\_var type="double"/$>$ $<$/publish$>$& D & (double) Message created from decoded hexadecimal string. & Defined by \xmltag{format} \\ \hline
$<$outgoing\_hex\_moos\_var/$>$ & \$ & Encoded hexadecimal string. &  \\ \hline
\hline \textbf{Queue} &&& \\ \hline\hline
receive= &&&\\incoming\_hex\_moos\_var,... & \$ & incoming\_hex\_moos\_var contains a hexadecimal string from the micromodem to route to this queue. & see below \\ 
\hline $<$incoming\_hex\_moos\_var/$>$ & \$ & incoming\_hex\_moos\_var contains a hexadecimal string from the micromodem to route to this queue. & see below \\  \hline
ACOMMS\_ACK& \$ & Notification of acknowledged messages &  \\ \hline
ACOMMS\_EXPIRE& \$ & Notification of expired messages (ttl exceeded) &  \\ \hline
ACOMMS\_SQSIZE\_name & \$ & Notification of change in queue size (push or pop) & New size of queue (number of messages) \\ \hline
\hline \textbf{Driver} &&& \\ \hline\hline
ACOMMS\_NMEA\_IN & \$ & Incoming NMEA messages from the modem & See WHOI Micro-Modem Software Interface Guide \\ \hline
ACOMMS\_NMEA\_OUT & \$ & Outgoing NMEA messages to the modem & See WHOI Micro-Modem Software Interface Guide \\ \hline
\hline \textbf{MAC} &&& \\ \hline\hline
 \end{tabular}
 \caption{MOOS Variables Published by pAcommsHandler} \label{tab:pAcommsHandler:publish}
\end{table}

Similarly to the subscriptions, the some publishes done by pAcommsHandler
are defined in the .moos file or in message XML files. Again, instead of MOOS variables,
the table below sometimes indicates the .moos file keys or XML tags for which one can define
the publishes. See table \ref{tab:pAcommsHandler:publish} for a full list of the published variables.

\input{includes/pAcommsHandler_DCCL.tex}

\subsubsection{Priority Message Queuing Unit}

pAcommsHandler takes all the configured queues and maintains a stack of messages for each
  queue. when it is prompted by data by iMicroModem, it has a priority
  "contest" between the queues. the queue with the current highest
  priority (as determined by the \texttt{priority} and
  \texttt{priority\_time\_const} fields) is selected. The next message in
  that queue is then provided to the MicroModem to send. For modem
  messages with multiple frames per packet, each frame is a separate
  contest. Thus a single packet may contain frames from different
  queues (e.g. a rate 5 PSK packet has eight 256 byte frames. frame 1
  might grab a STATUS message since that has the current highest
  queue. then frame 2 may grab a BTR message and frames 3-8 are filled
  up with CTD messages (e.g. STATUS is in blackout, BTR queue is
  empty)).

For messages with \texttt{ack=1} (acknowledge requested), the last
  message continues to be re-sent (that is, it is not popped from the
  message queue) until the ACK is received from the modem (thus
  blocking the sending of other messages). Perhaps i will add max
  retries at some point soon. Messages with \texttt{ack=0} are popped
  and discarded when they are sent (no retries).

If you do not wish for dynamic growth of the priorities, simply
  set the \texttt{ttl} to the special value 0. Then the priorities grow as $P = V\_{base}$ and messages never expire. Note that this is the same as setting \texttt{ttl} = $\infty$.

\paragraph{Messages not to us are ignored} We choose modem id 0 as broadcast. thus messages with the destination
  field = 0 will always be read by all nodes and reported to the
  appropriate moos variable. Otherwise, we ignore messages unless they
  correspond to our modem id. so if you send a message to modem id 10,
  pAcommsHandler for modem ids $1 \rightarrow 9$, $11\rightarrow N$
  will ignore that. This is not the default behavior of the modem,
  which always reports data, regardless of the sender's ID.
  
\paragraph{Input (to pAcommsHandler) formats}\label{inputformat}

pAcommsHandler accepts several formats for the strings placed in the
various \texttt{outgoing\_hex\_moos\_var} moos variables (outgoing message queues). The
simplest is just a hexadecimal string of the appropriate length ($N-2$
bytes where $N=32, 64, \hbox{ or } 256$ depending on the modem
rate). This message will be queued to send to broadcast (modem id
0\footnote{the WHOI micromodem does not treat certain modem IDs
  specially (such as zero). All data are reported to the control
  computer, regardless of whether that machine is the intended
  recipient. However, the communications structure defined by
  pAcommsHandler and other \textit{tes} processes treat modem ID 0 as
  broadcast (much like xxx.xxx.xxx.255 is used for broadcast on TCP/IP
  networks). This means that incoming messages are read if they are to
  our modem ID or to modem ID 0.}). An example:
\begin{verbatim}
OUT_CTD_HEX_32B: 20086850a232ccd2be62e1f36e6b02fffa92385bce8fa2109efa8902ddf3a02
\end{verbatim}
would queue a CTD message to be sent to broadcast (modem ID 0), given the above configuration file.

pAcommsHandler also accepts a string of key=value, comma delimited
fields allowing for more flexibility. Currently, the only fields
supported are \texttt{data=} (required, of course) and \texttt{dest=}
for the intended destination modem\_id:
\begin{verbatim}
OUT_CTD_HEX_32B: dest=3,data=20086850a232ccd2be62e1f36e6b02fffa92385bce8fa2109efa8902ddf3a02
\end{verbatim}
would queue a CTD message to be sent to id 3.


\paragraph{Output (from pAcommsHandler) formats} 

Upon receipt of a message from the Micro-Modem, the first byte of the message is
checked against the moos CCL type (0x20) and any of the additional
\texttt{receive\_CCL} \texttt{CCLIdentifierByte} given in the .moos
file. if none of these match, the message is disregarded. If the
message matches the moos CCL type (0x20), the second byte is examined
for the \texttt{id}. If the \texttt{id} matches one of the
\texttt{receive} fields in the .moos file, the hexadecimal string is
stripped of its first two bytes and placed in the correspoding
\texttt{incoming\_hex\_moos\_var} moos variable. The community name is set to the
sender's variable ID\footnote{use CMOOSMsg::GetCommunity() to extract
  the community}. For example, the modem reports:\footnote{see Micro-Modem Mainboard Software Interface
  Guide at \url{http://acomms.whoi.edu/umodem/documentation.html} for
  details on these messages}
\begin{verbatim}
$CARXD,3,0,0,1,20016850a232ccd2be62e1f36e6b02fffa92385bce8fa2109efa8902ddf3a02
\end{verbatim} %$

pAcommsHandler places the message in the appropriate moos variable, which
for the example .moos file here is \texttt{IN\_CTD\_HEX\_32B}:

\begin{verbatim}
IN_CTD_HEX_32B: 20016850a232ccd2be62e1f36e6b02fffa92385bce8fa2109efa8902ddf3a02 
{Community=3}
\end{verbatim}

from here either pGeneralCodec or pAcommsHandler's DCCL unit will decode the message (or pREMUSCodec for CCL messages). 

\subsubsection{Modem Driver Unit}

The Modem driver unit current supports the WHOI Micro-Modem acoustic modem. It is tested to work with revision 0.93.0.30 of the Micro-Modem firmware, but is known to work with older firmware (at least 0.92.0.85). The following commands of the WHOI Micro-Modem are implemented:

Modem to Control Computer (\$CA):
\begin{itemize}
\item \$CAACK - acknowledgement of sent message. 
\item \$CADRQ - data request. 
\item \$CARXD - received hexadecimal data.
\item \$CAREV - revision number and heartbeat. Used to check for correct clock time and modem reboots.
\item \$CAERR - error message.
\end{itemize}

Control Computer to Modem (\$CC). Also implemented is the NMEA acknowledge (e.g. \$CACYC for \$CCCYC):
\begin{itemize}
\item \$CCTXD - transmit data. 
\item \$CCCYC - initiate a cycle.
\item \$CCCLK - set the clock. The clock is set on startup until a suitably value within 1 second of the computer time is reported back. If the modem reboots (\$CAREV,...,INIT), the clock is set again.
\item \$CCCFG - configure NVRAM value. All values passed to \texttt{cfg=} will be passed to \$CCCFG at startup. 
\item \$CCCFQ - query configuration values. \$CCCFQ,ALL is sent after all the \$CCCFG lines to log the NVRAM parameters.
\end{itemize}

To directly monitor the modem feed, subscribe to ACOMMS\_NMEA\_IN and ACOMMS\_NMEA\_OUT. If you wish to control the modem directly, write a valid \$CC NMEA string (without newline or carriage return) to ACOMMS\_NMEA\_OUT.

\subsubsection{Medium Access Control (MAC) Unit}

...documentation coming soon...
