\subsubsection{Brief Overview}
\paragraph{Problem}

\paragraph{Background}

\paragraph{Solution}
pGeneralCodec is an process that proposes to be a practical first-pass solution to the difficult problem posed here. 



\subsubsection{Parameters for the pGeneralCodec Configuration Block}
\paragraph{Example .moos file}
The moos file is simple since the bulk of the configuration is stored in separate XML files (see section \ref{sec:ex_xml} for the configuration of these files):

\begin{small}\begin{verbatim}
ProcessConfig = pGeneralCodec
{
  // available to all moos processes.
  AppTick    = 4
  CommsTick  = 4

  // available to all tes moos processes

  //verbose, terse, quiet
  verbosity = verbose

  message_file = example1.xml
  message_file = example2.xml
  message_file = bobs_special_command_set.xml

  // initialize variable at the top of the moos file  
  global_initializer.double = LAT_ORIGIN = LatOrigin
  global_initializer.double = LONG_ORIGIN = LongOrigin
  global_initializer.double = MODEM_ID_PATH = modem_id_lookup_path


  // initialize variable here
  initializer.string = VEHICLE_NAME = unicorn
  initializer.string = VEHICLE_TYPE = auv
}
\end{verbatim}
\end{small}

\paragraph{Filling out the .moos file}
\begin{itemize}
\item \verb|verbosity|: choose verbose for full text terminal output, terse for symbolic heartbeat output, and quiet for no terminal output.
\item \verb|message_file|: path to an XML file containing a message set of one or messages.

\end{itemize}

\subsubsection{MOOS variables subscribed to by pGeneralCodec:}
All the variables subscribed to by pGeneralCodec are configured within the message XML files. See section \ref{sec:ex_xml} and beyond for details on filling out and interpreting these XML files. Thus, in the following table instead of MOOS variables, XML tags from the message XML file are listed. For each \verb|<message />| defined, a subscription takes place for the MOOS variable specified at run time within the tag. For example, the .moos file includes a file \verb|message_file = example1.XML|, and \verb|example1.XML| contains the tag \verb|<incoming_hex_moos_var>STATUS_HEX_32B</incoming_hex_moos_var>|. Thus, \verb|STATUS_HEX_32B| is subscribed for.

\renewcommand{\arraystretch}{1.5}
\begin{minipage}[c]{0.8\textwidth}
  \centering
  \mbox{
  \footnotesize
\begin{tabular}{|p{0.3\textwidth}|c|p{0.5\textwidth}|p{0.25\textwidth}|}

\hline XML tag specifying a MOOS variable & Type & Description & Published by \\ \hline \hline
$<$incoming\_hex\_moos\_var/$>$ & \$ & Hexadecimal string to decode (probably from MicroModem). & pAcommsHandler (or MOOSBlink) \\ \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,...) & pNaFCon (PLUSNET\_MESSAGES) or others \\ \hline
$<$trigger\_moos\_var/$>$ & \$ or D & A publish here triggers the creation of this message. The contents may contain message parts or not. & pNaFCon (PLUSNET\_MESSAGES) or others \\ \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,...). & pNaFCon (PLUSNET\_MESSAGES) or others \\ \hline
 \end{tabular}
  \normalsize}
\end{minipage}

\subsubsection{MOOS variables published by pGeneralCodec:}
Similarly to the subscriptions, the publishes done by pGeneralCodec are all defined in the message XML files. Again, instead of MOOS variables, the table below indicates the XML tags for which one can define the publishes. 

\renewcommand{\arraystretch}{1.5}
\begin{minipage}[c]{0.8\textwidth}
  \centering
  \mbox{
  \footnotesize
\begin{tabular}{|p{0.3\textwidth}|c|p{0.5\textwidth}|p{0.25\textwidth}|}

\hline XML tag specifying a MOOS variable & Type & Description & Format \\ \hline \hline
$<$outgoing\_hex\_moos\_var/$>$ & \$ & Encoded hexadecimal string (likely to be subscribed for by pAcommsHandler). & if the destination is NOT broadcast (\textit{modem\_id=0}: ``Dest=\textit{modem\_id}, HexData=\textit{2N character hex string where N is bytes defined by $<$size $/>$}'', else ``\textit{2N character hex string}'' \\ \hline
$<$publish$>$ $<$moos\_var type="string"/$>$ $<$/publish$>$& \$ & (string) Message created from decoded hexadecimal string. & Defined by $<$format $/>$ \\ \hline
$<$publish$>$ $<$moos\_var type="double"/$>$ $<$/publish$>$& D & (double) Message created from decoded hexadecimal string. & Defined by $<$format $/>$ \\ \hline

 \end{tabular}
  \normalsize}
\end{minipage}

\subsubsection{Usage}
\paragraph{Compilation}
pGeneralCodec depends on the boost string library and the xerces-c XML parsing library in addition to the libraries included in MOOS and moos-ivp-local.

\begin{itemize}
\item boost: reference \textit{http://www.boost.org/} or look for your distribution's boost developer package (libboost-dev in debian/ubuntu).
\item xerces-c: reference \textit{http://xerces.apache.org/xerces-c/} or look for your distribution's xerces-c developer package (libxerces28-dev in debian/ubuntu as of this writing).
\end{itemize}

\paragraph{Running}
pGeneralCodec can be run using pAntler or standalone with the following arguments:
\begin{verbatim}
> pGeneralCodec [pGeneralCodec.moos] [pGeneralCodec] [-q]
\end{verbatim}
Parameters in [ ] are optional\footnote{you will almost always want to specify a .moos file, however}: defaults are given above. The -q flag tells pGeneralCodec to start and quit after outputting all the message information to stdout. This is very useful during message design.


All the messages defined in the XML message files included in the
 .moos file define the entirety of the available message set. First, let us give a
 brief background on XML (e\textbf{X}tensible \textbf{M}arkup
 \textbf{L}anguage). XML files contain tags (like
 \verb|<name />|) that are considered ``metadata'' and define both
 the structure of the following data and the contents. Order of the
 tags does not matter for a given level unless explicitly
 specified. Text data resides both in the tags (like
 \verb|<name>bob</name>| or as attributes of the tag (such as
 \verb|<name id="1245"></name>|). XML files can be edited with any
 text editor. For more information on XML consult any number of books
 on the subject or browse the internet. XML is a very widely used
 format for storing data that can be both read by both people and
 computers. Also see section \ref{sec:ex} for further examples. Let's call this file example1.xml, which we will use in two following examples:
\begin{small}
\input{includes/example1.xml}
\end{small}


\paragraph{Designing a publish triggered message}  \label{sec:design}
We will look at two scenarios and detail how to design a proper message file for each scenario. We will reference the example file given in section \ref{sec:ex_xml} for both scenarios.

Scenario: you want to command an surface craft to move to a new location:
\begin{enumerate}
\item Identify the data: location (x (\verb|goto_x|) and y (\verb|goto_y|) on a local grid). you also want to specify a speed (\verb|goto_speed|) at which it should transit, whether it should have lights (\verb|lights_on|) on or not, and finally a string (\verb|special_instructions|) with possible special instructions. All these data will come in to a moos variable \verb|OUTGOING_COMMAND| on a string like: 
\begin{small}
\begin{verbatim}
OUTGOING_COMMAND: Destination=3,CommandType=GoTo,goto_x=351,goto_y=294,
                  lights_on=true,special_instructions=make_toast,goto_speed=2.3
\end{verbatim}
\end{small}
\item Type the data (i.e. is it an int, a float, a string?) and give the ranges and precisions needed: 
\begin{itemize}
\item \verb|goto_x|: integer (in meters) (\verb|int|) that will operate on a (positive valued) local grid not to exceed 10 km in either dimension. 
\item \verb|goto_y|: same as \verb|goto_x|.
\item \verb|goto_speed|: speed in m/s. the vehicle cannot exceed 3 m/s and does not go backwards. we would like to give precise speeds to the hundredths place. thus, we need a \verb|float| ranging from 0 to 3 with precision 2.
\item \verb|lights_on|: simply a flag (boolean value) whether to have our lights on or off. thus, we need a \verb|bool| \textit{message\_var}.
\item \verb|special_instructions|: We want a field that can hold any string of characters, but we know it will not exceed ten characters. thus, we need a \verb|string| \textit{message\_var}.
\end{itemize}
\item Putting all this together, we can define the \verb|<layout />| portion of the first message defined in section \ref{sec:ex_xml}. We do not need any \verb|<moos_var />| tags within the \textit{message\_var}s since all the data are contained in the contents of the trigger variable message (\verb|OUTGOING_COMMAND|). That is, when we leave out the \verb|<moos_var />|, pGeneralCodec will insert \verb|<moos_var>OUTGOING_COMMAND</moos_var>|, which is exactly what we want. For example, taking one of the \textit{message\_var}s:
\begin{small}\begin{verbatim}
      <int>
        <name>goto_x</name>
        <max>10000</max>
        <min>0</min>
      </int>
\end{verbatim}\end{small}
is exactly the same as saying 
\begin{small}\begin{verbatim}
      <int>
        <name>goto_x</name>
        <moos_var>OUTGOING_COMMAND</moos_var>
        <max>10000</max>
        <min>0</min>
      </int>
\end{verbatim}\end{small}

\item Now we can fill out the rest of the tags on the \verb|<message />| level:
\begin{itemize}
\item \verb|<name>GoToCommand</name>|: just a name so we can identify this message quickly when reading through the XML.
\item \verb|<outgoing_hex_moos_var>OUT_GOTO_HEX</outgoing_hex_moos_var>|: we will publish our hex strings here for consumption by the low level modem stack processes (probably pAcommsHandler \verb|send=OUT_GOTO_HEX...|). the publishes will look a bit like:
\begin{small}
\begin{verbatim}
OUT_GOTO_HEX: Dest=3,HexData=a9385bc098109830a9385bc0981098a9385bc098109830a9385bc0981098
\end{verbatim}
\end{small}

\item \verb|<incoming_hex_moos_var>IN_GOTO_HEX</incoming_hex_moos_var>|: where we expect to receive incoming messages to decode (probably from pAcommsHandler \verb|receive=IN_GOTO_HEX...|). messages should be pure hex with the community set to the sending \textit{modem\_id}. An example for the received message on \textit{modem\_id}=3 if the sending node (say a topside command computer) is \textit{modem\_id}=1:
\begin{small}
\begin{verbatim}
IN_GOTO_HEX: a9385bc098109830a9385bc0981098a9385bc098109830a9385bc0981098 
{Community=1}
\end{verbatim}
\end{small}
\item \verb|<destination_moos_var key="Destination">OUTGOING_COMMAND</destination_moos_var>|: we want to pull the destination \textit{modem\_id} from the same string as the data (moos variable \verb|OUTGOING_COMMAND| and it is found in a key called ``Destination''.
\item \verb|<trigger>publish</trigger>|: we are creating this message on a \textbf{publish} (to \verb|OUTGOING_COMMAND|).
\item \verb|<trigger_moos_var mandatory_content="CommandType=GoTo">OUTGOING_COMMAND</trigger_moos_var>|: \verb|OUTGOING_COMMAND| is the trigger variable and it must contain the substring \verb|CommandType=GoTo|. That is, other commands might be published here (e.g. \verb|CommandType=Loiter|, \verb|CommandType=Track|) and we do not define the message structure of those here (this particular \verb|<message></message>| is only for a GoTo message). Other messages can be created to encode/decode these other command types.
\item \verb|<size>30</size>|: we want this message to fit in a WHOI micromodem FSK frame (32 bytes) and thus we have 30 bytes to work with (pAcommsHandler needs 2 bytes of header).
\end{itemize}
\item Finally, we fill out the \verb|<publish />| section which indicates where (i.e. what moos variables) and how (what format and which part(s) of the message) pGeneralCodec should publish decoded messages upon receipt of hex from other vehicles. Each \verb|<publish />| indicates a separate action that is taken upon receipt of a message. As many \verb|<publish />| sections as desired may be included for a given message. So, for our example message, we want to replicate the original string (a common practice):
\begin{small}\begin{verbatim}
INCOMING_COMMAND: CommandType=GoTo,goto_x=351,goto_y=294,
                  lights_on=true,special_instructions=make_toast,goto_speed=2.3
\end{verbatim}\end{small}
to do this we fill out a publish \verb|<all />|. This is the simplest form of the \verb|<publish />| section:
\begin{small}\begin{verbatim}
    <on_receipt>
      <publish>
        <moos_var>INCOMING_COMMAND</moos_var>
        <all />
      </publish>
    </on_receipt>
\end{verbatim}\end{small}
this says to take every \textit{message\_var} and make a ``key=value'' comma-delimited string from it. the above \verb|<publish />| block is a shortcut for a much longer form:
\begin{small}\begin{verbatim}
    <on_receipt>
      <publish>
        <moos_var>INCOMING_COMMAND</moos_var>
        <format>type=goto,goto_x=%1%,goto_y=%2%,lights_on=%3%,
        special_instructions=%4%,goto_speed=%5%</format>
        <message_var>goto_x</message_var>
        <message_var>goto_y</message_var>
        <message_var>lights_on</message_var>
        <message_var>special_instructions</message_var>
        <message_var>goto_speed</message_var>
      </publish>
    </on_receipt>
\end{verbatim}\end{small}
These two blocks are functionally identical.

We may want to also publish the \verb|special_instructions| to another moos variable, so that:
\begin{small}\begin{verbatim}
SPECIAL_INSTRUCTIONS: special_instructions=make_toast,lights_on=true
\end{verbatim}\end{small}
we can do this with another publish block:
\begin{small}\begin{verbatim}
    <publish>
      <moos_var>SPECIAL_INSTRUCTIONS</moos_var>
      <format>special_instructions=%1%,lights_on=%2%</format>
      <message_var>new_instructions</message_var>
      <message_var>lights_on</message_var>
    </publish>
\end{verbatim}\end{small}
in this case the \verb|<format />| block is necessary because the default would be \\ 
\verb|<format>new_instructions=%1%,lights_on=%2%</format>| not \\
\verb|<format>special_instructions=%1%,lights_on=%2%</format>|.
\end{enumerate}

Those are the basics to designing a \textbf{publish} triggering message.

\paragraph{Designing a time triggered message}
Scenario: we need a status message that grabs data from various moos variables and publishes them (encoded) on a time interval. We will not go into as much detail here, but rather highlight the changes from the previous scenario.
\begin{itemize}
\item you will notice
\begin{small}\begin{verbatim}
    <trigger>time</trigger>
    <trigger_time>30</trigger_time>
\end{verbatim}\end{small}
instead of 
\begin{small}\begin{verbatim}
    <trigger>publish</trigger>
    <trigger_moos_var mandatory_content="CommandType=GoTo">OUTGOING_COMMAND</trigger_moos_var>
\end{verbatim}\end{small}
this indicates that a message should be made on a time interval (given by \verb|<trigger_time />|, which is every 30 seconds here), rather than on a publish to some moos variable.
\item you will notice that all the \textit{message\_var}s have a \verb|<moos_var />| tag, which was omitted in the previous example since we were taking data from the trigger variable. Obviously, there is no trigger variable now so we must specify a location for the data to come from (in the moos db). The newest available value will be used when the message needs to be made. This means there is no guarantee that the data is fresh. Thus, you should use moos variables that are often updated for a \verb|<trigger>time</trigger>| message. If this is not the case, a \verb|<trigger>publish</trigger>| message (see previous scenario) may be a better choice.
\item the format of the value read from the \verb|<moos_var />| can have several options. First, if the \textit{message\_var} is of a numeric type (\verb|<int />|, \verb|<float />|, \verb|<bool />|) and the \verb|<moos_var />| is a double, the value of the double is used as is (with appropriate rounding and type casting). If the \textit{message\_var} is a string, two options are available. First, the pGeneralCodec looks for a substring of the form:
\begin{small}\begin{verbatim}
name=value
\end{verbatim}\end{small}
within the string and picks out the value to send for the message. If there is no such \verb|name=| substring, the entire string is converted to the appropriate form. An example: we have a \verb|<float />| called \verb|<name>my_float</name>| that has a tag \\
\verb|<moos_var>SOME_FLOAT_VARIABLE</moos_var>|: 
\begin{itemize}
\item if
\begin{small}\begin{verbatim}
(double)SOME_FLOAT_VARIABLE: 3.56
\end{verbatim}\end{small}
then 3.56 is sent.
\item if instead 
\begin{small}\begin{verbatim}
(string)SOME_FLOAT_VARIABLE: "my_float=3.56"
\end{verbatim}\end{small}
then 3.56 is still sent.
\item if instead
\begin{small}\begin{verbatim}
(string)SOME_FLOAT_VARIABLE: "3.56"
\end{verbatim}\end{small}
again, 3.56 is sent.
\item Finally, if some other string like
\begin{small}\begin{verbatim}
(string)SOME_FLOAT_VARIABLE: "blah=3.56"
\end{verbatim}\end{small}
then \verb|blah=3.56| is converted (using streams) to a float, which will probably be zero or something else undesired. In other words, this case is not what you want, whereas the above three are fine.
\end{itemize}
\end{itemize}

\paragraph{Message XML file reference: allowed tags} Let us now give a description of all the allowed tags:

\begin{itemize}
\item \verb|<?xml version="1.0" encoding="UTF-8"?>|: specifies the file is XML. All you need to know is that this must be the first line of every message XML file.
\item \verb|<message_set />|: the root element. All XML files must have a single root element. Since we are define a set of messages (one or more per file), this is a logical choice of name for the root element. [mandatory, one allowed].
\item \verb|<message />|: defines the start of a message. [mandatory, one or more allowed].
\begin{itemize}
\item \verb|<name />|: a human readable name for the message. This is not used internally at this point in time. [mandatory, one allowed]
\item \verb|<id />|: an unsigned eight bit integer (0-255) that identifies this message within a network. very similar to the CCL identifier, but for DCCL messages. The CCL identifier occupies the most significant byte (MSB) of the message followed by this id which takes the second MSB. \textit{This must be unique within a network as this id determines the message decoding} [mandatory, one allowed]
\item \verb|<trigger />|: how the message is created. Currently this field must take the value ``publish'' (meaning a message is created on a publish event to a certain moos variable) or ``time'' (a message is created on a certain time interval). [mandatory, one allowed]
\item \verb|<trigger_moos_var />|: used if \verb|<trigger>publish</trigger>|, this field gives the moos variable that pGeneralCodec should look for publishes to in order to trigger the creation of this message [mandatory if and only if \verb|<trigger>publish</trigger>|]. optional attribute \verb|mandatory_content| specifies a string that must be a substring of the contents of the trigger variable in order to trigger the creation of a message. For example, if you wanted to create a certain message every time \verb|COMMAND| contained the string \verb|CommandType=GoTo...| but no other time, you would specify \\ \verb|mandatory_content="CommandType=GoTo"| within this tag.
\item \verb|<trigger_time />|: used if \verb|<trigger>time</trigger>|, this field gives the time interval pGeneralCodec should create this message. For example, a value of \\ \verb|<trigger_time>10</trigger_time>| would mean a message was created every ten seconds. [mandatory if and only if \verb|<trigger>time</trigger>|].
\item \verb|<size />|: the size of the message in bytes. There are eight bits (binary digits) to a byte. Use $N$ here for messages passed to the micromodem where $N$ is the desired micromodem frame size ($N=$32, 64, or 256 depending on the rate). If the \verb|<layout />| of the message exceeds this size, pGeneralCodec will exit on startup with information about sizes, from which you can remove or reduce the size of certain \textit{message\_var}s.
\item \verb|<outgoing_hex_moos_var />|: where to publish the encoded message (as a hexadecimal string). [optional, one allowed. default is \verb|OUT_<name/>_HEX_<size/>B|].
\item \verb|<incoming_hex_moos_var />|: where to look for messages (hex string) to decode. [optional, one allowed. default is \verb|IN_<name/>_HEX_<size/>B|].
\item \verb|<destination_moos_var />|: moos variable to find where this message should be sent. Specify attribute ``key='' to specify a substring to look for within the value of this moos variable. For example, if \verb|COMMAND| contained the string \verb|Destination=3| and you want this message sent to modem\_id 3, then you should set \verb|key=Destination| to properly parse that string. [optional: default is 0 (broadcast), one allowed].
\item \verb|<layout />|: defines the message structure itself (what fields [the message variables or \textit{message\_var}s] the message contains and how they are to be encoded). [mandatory, one allowed].
\begin{itemize}
\item \verb|<static />|: a \textit{message\_var} that is not actually sent with the message but can be used to include in received messages (\textit{publishes}). [optional, one or more allowed]. 
\begin{itemize}
\item \verb|<name />|: the name of this \textit{message\_var}. [mandatory, one allowed].
\item \verb|<value />|: the value of this static variable. [mandatory, one allowed].
\end{itemize}
\item \verb|<bool algorithm=""/>|: a boolean (true or false) \textit{message\_var}  The optional parameter \verb|algorithm| allows you to perform certain algorithms on the data before encoding. See below. [optional, one or more allowed]. 
\begin{itemize}
\item \verb|<name />|
\item \verb|<moos_var />|: the moos variable from which to pull the value of this field. [optional if \verb|<trigger>publish</trigger>|: default is trigger\_moos\_var; mandatory if \verb|<trigger>time</trigger>|, one allowed]. 
\end{itemize}
\item \verb|<int algorithm=""/>|: an integer \textit{message\_var} [optional, one or more allowed]. 
\begin{itemize}
\item \verb|<name />|
\item \verb|<moos_var />|
\item \verb|<max />|: the maximum value this field can take. [mandatory, one allowed].
\item \verb|<min />|: the minimum value this field can take. [mandatory, one allowed].
\end{itemize}
\item \verb|<float algorithm=""/>|: a floating point \textit{message\_var} [optional, one or more allowed].
\begin{itemize}
\item \verb|<name />|
\item \verb|<moos_var />|
\item \verb|<max />|
\item \verb|<min />|
\item \verb|<precision />|: an integer that specifies the number of decimal digits to preserve. Negatives are allowed. For example, \verb|<precision>2</precision>| rounds 1042.1234 to 1042.12; \verb|<precision>-1</precision>| rounds 1042.1234 to 1.04e3. [mandatory, one allowed].
\end{itemize}
\item \verb|<string algorithm=""/>|: an ASCII string \textit{message\_var} [optional, one or more allowed].
\begin{itemize}
\item \verb|<name />|
\item \verb|<moos_var />|
\item \verb|<max_length />|: the length of the string value in this field. Longer strings are truncated. \verb|<max_length>4</max_length>| means ``ABCDEFG'' is sent as ``ABCD''. [mandatory, one allowed].
\end{itemize}
\item \verb|<enum algorithm=""/>|: an enumeration \textit{message\_var} [optional, one or more allowed].
\begin{itemize}
\item \verb|<name />|
\item \verb|<moos_var />|
\item \verb|<value />|: a possible value (string) the enum can take. Any number of values can be specified. [mandatory, one or more allowed].
\end{itemize}
\end{itemize}
\item \verb|<on_receipt />|: begins a set of actions to be performed when a message of this type is received from another vehicle. [mandatory, one allowed].
\begin{itemize}
\item \verb|<publish />|: defines a single output value upon receipt of a message. Any number of publishes containing any subset of the \textit{message\_var}s can be specified. [mandatory, one or more allowed].
\begin{itemize}
\item \verb|<moos_var />|: the name of the moos variable to publish to. If desired, a format string is allowed here as well (e.g. \verb|%1%_NAV_X| will fill \verb|%1%| with the first \textit{message\_var}). See the \verb|<format />| tag description for more info. [mandatory, one allowed].
\item \verb|<format />|: a string conforming to the format string syntax of the boost::format \footnote{see the syntax of the \textbf{format-string} at \textit{http://www.boost.org/doc/libs/1\_37\_0/libs/format/doc/format.html\#syntax}} library. This field will specify the format of the string published to the moos variable defined in \verb|<moos_var />|. At its simplest it is a string of incrementing numbers surrounded by \%\%. Or, instead, you may also use a printf style string, using \%d for int  \textit{message\_var}, \%lf for floats, and \%s for strings, bools and enums. [optional: default is \verb|name1=%1%,name2=%2%,name3=%3%|, where \verb|name1| is the name of the first \verb|<message_var />| field to follow, \verb|name2| is the second, etc. exception: default is \verb|%1%| if only a single \verb|<message_var />| defined. one allowed].
\item \verb|<message_var algorithm=""/>|: the name (\verb|<name />| above) of a \textit{message\_var} contained in this message (i.e. an \verb|<int />|, \verb|<bool />|, etc.) the values of these fields upon receipt of a message will be used to populate the format string and the result will be published to \verb|<moos_var />|. The optional parameter \verb|algorithm| allows you to perform certain algorithms on the data after receipt before publishing. See below. [mandatory unless \verb|<all />| used, one or more allowed].
\item \verb|<all />|: equivalent to \verb|<message_var />| for all the \textit{message\_var}s in the message. This is a shortcut when you want to publish all the data in a human readable string. [optional, one allowed].
\end{itemize}
\end{itemize}
\item \verb|<queuing />|: optional section used by pAcommsHandler to handle message queueing. See section \ref{sec:xmlqueue} for details.
\end{itemize}
\end{itemize}

\paragraph{Algorithms}
You can perform a number of simple algorithms on data either before encoding (specified in the \textbf{message\_var} tag (e.g. \verb|<string algorithm="" />|) or after receipt (specified in the \verb|<message_var />| tag. You can apply more than one algorithm by separating them with commas and they are processed in the order given. The currently implemented algorithms include:
\begin{itemize}
\item \verb|to_upper|: converts string, enum, or bool to uppercase
\item \verb|to_lower|: converts string, enum, or bool to lowercase
\item \verb|angle_0_360|: wraps float or int angle in degrees into the range of [0, 360)
\item \verb|angle_-180_180|: wraps float or int angle in degrees into the range of [-180, 180)
\item \verb|lon2utm_x|: converts longitude to a local utm coordinate (meters) used by LAMSS\footnote{we define a latitude/longitude origin near our basis of operations. From this datum we calculate the UTM northings (y) and eastings (x). All further UTM calculations are the offset from this datum point. This offset is what is returned by this algorithm. Contact me if you need more information on this.}. Requires \verb|LatOrigin| and \verb|LongOrigin| to be specified at the top of the moos file. Since a UTM conversion requires a lon/lat pair, you must specify the latitude variable here to pair with by adding a colon after this algorithm followed by the name of the latitude variable. e.g. \verb|<message_var algorithm="lon2utm_x:our_lat">our_lon</message_var>| converts \verb|our_lon| to a local x (easting) using \verb|our_lat| as the latitude point.
\item \verb|lat2utm_y|: similar to \verb|lon2utm_x| but for latitude. \\ e.g. \verb|<message_var algorithm="lat2utm_y:our_lon">our_lat</message_var>| converts \verb|our_lat| to a local y (northing) using \verb|our_lon| as the longitude point.
\item \verb|utm_x2lon|: the reverse conversion from x to longitude. similarly to the latitude, longitude to x,y conversion you must pair x and y. e.g., \\ \verb|<message_var algorithm="utm_x2lon:our_y">our_x</message_var>|
\item \verb|utm_y2lat|: example: \verb|<message_var algorithm="utm_y2lat:our_x">our_y</message_var>|
\item \verb|modem_id2name|: converts a WHOI modem\_id to a vehicle name. requires a file (path given in the .moos as \verb|modem_id_lookup_path={pathto}/modemidlookup.txt|. an example file:
\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}
if no match is found, the modem\_id is returned as a string (e.g. "10").
\item \verb|name2modem_id|: performs the (case insensitive) reverse lookup on the same file. if no match is found, \verb|atoi(name.c_str())| is returned (probably zero unless you passed something like "4" to this function).
\item \verb|modem_id2type|: similar to \verb|modem_id2name| but returns the type of the vehicle (ship, auv, etc.)
\end{itemize}

\subsubsection{Details}
\begin{itemize}
\item the code is comprised of:
\begin{enumerate}
\item \verb|CMOOSApp| extended class \verb|CpGeneralCodec| in \verb|pGeneralCodec.cpp|. This is the moos app that you run.
\item \verb|libdccl|: library that performs most of the actual work. This library can be called as a standalone (i.e. without MOOS) C++ dynamic library (libdccl.so). See section \ref{sec:libdccl} for details.
\end{enumerate}

\item We may want to know the actual layout of the binary/hex message. Let us explain it with an example; for the first example message in \verb|example1.xml| given in section \ref{sec:ex_xml}, if we run pGeneralCodec we get information about that message:
\begin{small}\begin{verbatim}
        type (static):
                value: {goto}
                size [bits]: [0]
        goto_x (int):
                source: {OUTGOING_COMMAND}
                [min, max] = [0,10000]
                size [bits]: [14]
        goto_y (int):
                source: {OUTGOING_COMMAND}
                [min, max] = [0,10000]
                size [bits]: [14]
        lights_on (bool):
                source: {OUTGOING_COMMAND}
                size [bits]: [1]
        new_instructions (string):
                source: {SPECIAL_INSTRUCTIONS}
                max_length: {10}
                size [bits]: [80]
        goto_speed (float):
                source: {OUTGOING_COMMAND}
                [min, max] = [0,3]
                precision: {2}
                size [bits]: [9]
\end{verbatim}\end{small}
the calculated sizes are used to pack the message like so (\verb|{#}| equals size of field in bits), where left to right is the same as reading the hex string from left to right:
\begin{small}\begin{verbatim}
[[0 {122}][goto_x {14}][goto_y {14}][lights_on {1}][new_instructions {80}][goto_speed {9}]]
\end{verbatim}\end{small}
where \verb|[0 {122}]| means zero fill the front of the message to the full size (30 bytes = 240 bits minus 118 for other fields = 122). Byte boundaries are dissolved and encoded as a string ``ABCDEF...'' where the most significant byte (MSB, or leftmost 8 bits) is 0xAB, second MSB is 0xCD, etc. Encoding and decoding are done by functions available in \verb|binary.h| in \verb|libtes_util.a|.
\item The encoding of each \textit{message\_var} is done as an unsigned integer, with the exception of strings, which are store as ASCII. The value 0 (all bits zero) always indicates "not specified" or "Not a Number" (nan). This means that the user did not specify any value for this field, specified a value causing overflow (\verb|<int/>| or \verb|<float/>| greater than \verb|<max/>| or less than \verb|<min/>|), or provided a value for an \verb|<enum/>| that did not match any of the enumerate's \verb|<value/>| options. Along with this rule, the method for encoding and decoding is summarized below:

\begin{small}\begin{tabular}{|p{5em}|p{8em}|p{14em}|p{14em}|}
\hline message\_var & size (bits) & encode & decode \\ 
\hline static & 0 & not sent & not sent \\ 
\hline bool & 2 & $val_{enc}$ = ($val$ == to\_lower("true") OR $val$ != 0) ? 2 : 1 & $val$=($val_{enc}$==2) ? true : false \\ 
\hline enum & $ceil(log_2(total\_enums + 1))$ & $val_{enc}$ = 1 + index to array of enum values based on order they were declared & $val$ = value at index $val_{enc}$ -1  \\ 
\hline string & $max\_length \cdot 8$ & string is filled at end with zeros (\verb|'\0'|) to $max\_length$ then encoded using ASCII byte values & ASCII, ignoring null termination chars (if any) \\ 
\hline int & $ceil(log_2(max-min + 2))$ & $val_{enc}$ = $round(val - min, 0) + 1 $ & $val = val_{enc} + min-1$  \\ 
\hline float & $ceil(log_2((max-min)\cdot 10^{precision} + 2))$ & $val_{enc}$ = $round((val - min)\cdot 10^{precision}$, 0) + 1  & $val$ = ($val_{enc} - 1)/10^{precision} + min$  \\ 
\hline 
\end{tabular} 
\end{small}
where $val$ is the original (and decoded) value, $val_{enc}$ is the encoded value, $min$, $max$, $max\_length$, $precision$ are the contents of the \verb|<min/>|, \verb|<max/>|, \verb|<max_length/>|, and \verb|<precision/>| tags, respectively, and round($x$,0) means round $x$ to the nearest integer.

An example. Say you have the following XML file:
\begin{small}\begin{verbatim}
...
    <id>1</id>
    <layout>
	  <bool>
        <name>B</name>
	  </bool>
	  <enum>
        <name>E</name>
        <value>cat</value>
        <value>dog</value>
        <value>mouse</value>
	  </enum>
      <string>
        <name>S</name>
        <max_length>4</max_length>
      </string>
	  <int>
        <name>I</name>
        <max>100</max>
        <min>-50</min>	  
	  </int>
	  <float>
	    <name>F</name>
        <max>100</max>
        <min>-50</min>	  
        <precision>2</precision>
	  </float>      
	</layout>
...
\end{verbatim}\end{small}
below the size of each \textit{message\_var} and its encoded value in decimal and binary are calculated for an example set of inputs:

\begin{small}\begin{tabular}{|p{5em}|p{5em}|p{5em}|p{8em}|p{16em}|}
\hline message\_var &  example $val$ & size (bits) & $val_{enc}$ (dec) & $val_{enc}$ (bin) \\ 
\hline B & true &   2 &  2  & 10 \\ 
\hline E & cat &    2 &  1  & 01 \\ 
\hline S & FAT &    32 & 1178686464 &   01000110 01000001 01010100 00000000 \\ 
\hline I & 34 &     8 &  85  & 01010101 \\
\hline F & -22.49 & 14 &  2752 & 00101011000000 \\  
\hline 
\end{tabular} 
\end{small}
and thus the whole message (zero padded from the most significant bits to the closest byte) sent would be 00000010 01010001 10010000 01010101 00000000 00010101 01001010 11000000 or 0x0251905500154AC0 plus two bytes of header (which in this case is 0x2001 so the full message sent is 0x20010251905500154AC0).
\end{itemize}

\subsubsection{Further examples} \label{sec:ex}
\begin{itemize}
\item I currently store our working message files in \verb|moos-ivp-local/data/acomms|. look for .xml files in this directory for further examples.
\item Probably the simplest message you can make (for a single string MOOS variable published to \verb|MY_STRING| that gets truncated at 30 chars (need two bytes for CCL and DCCL ids) and sent to broadcast):
\begin{small}\begin{verbatim}
<?XML version="1.0" encoding="UTF-8"?>
<message_set>
  <message>
    <name>SimpleStringSender</name>
    <id>1</id>    
    <outgoing_hex_moos_var>OUT_STRING_HEX</outgoing_hex_moos_var>
    <incoming_hex_moos_var>IN_STRING_HEX</incoming_hex_moos_var>
    <trigger>publish</trigger>
    <trigger_moos_var>MY_STRING</trigger_moos_var>
    <size>32</size>
    <layout>
      <string>
        <name>my_string</name>
        <max_length>30</max_length>
      </string>
    <on_receipt>
      <publish>
        <moos_var>INCOMING_COMMAND</moos_var>
        <all />
      </publish>
    <on_receipt>
  </message>
</message_set>
\end{verbatim}\end{small}
\end{itemize}
\subsubsection{Message XML reference sheet}
This is a quick reference of all the allowed tags with some comments about their use:

\begin{small}
\input{includes/message_xml_cheatsheet.xml}
\end{small}

\subsubsection{libdccl} \label{sec:libdccl}
Much of the functionality of pGeneralCodec is available in a C++ dynamic library that is standalone from MOOS. Thus, users can incorporate the encoding/decoding functionality of DCCL into their projects without MOOS. The library provides an simple API based heavily on the standard template library containers. Refer to the DCCL Doxygen document (\verb|doc/refman.pdf| in the dccl release) for the details of the interface. 

\subsubsection{Glossary}\label{sec:glossary}
\begin{itemize}
\item \textit{message\_var}: the term for a field within a message. a \textit{message\_var} can be of several types: int, bool, double, float, string, or enum. the \textit{message\_var}s are defined within the \verb|<layout />| part of the message.
\item \textit{modem\_id}: the number given to each whoi micromodem (this is like a variable MAC address) that defines senders and receivers. modem\_ids must be unique for each network and are configured using \verb|$CCCFG,SRC,#|, where \verb|#| is the modem\_id (integer from 0 to 127?). %$
\item \textit{publish}: the term for a given action to be performed upon receipt of a message. this term is used since this action will involve a moos publish to some variable (after some string parsing/formatting).
\item \textit{XML}: extensible markup language: a specification for defining a custom markup language, which is a set of annotations given to text to indicate structure. here we use XML to indicate the structure of a ``message'' and its subsequent breakup (``publishes'', during decoding)
\begin{itemize}
\item \textit{tag}: the name given to the ``metadata'' in the XML file. for example: the tag \verb|<message />| indicates the start and end of a message (this is ``metadata''), but nothing about what it contains (which is``data'')
\item \textit{attributes}: data contained within a tag. for example, in \verb|<int algorithm="to_upper"></int>|, \textbf{algorithm} is an attribute of the tag \textbf{int}. 
\item \textit{CDATA}: \textbf{C}haracter \textbf{DATA}, or the data contained within a tag or an attribute. for example, in \verb|<name>nav_x</name>|, \textbf{nav\_x} is CDATA.
\end{itemize}
\end{itemize}
