******************************************************************************
        Cathx M12 Camera Interface for MBARI Dorado AUVs

        09/18/2015 - V1.0
******************************************************************************

1. Overview

The Cathx module development resulted in not only in creating this directory
in the onboard tree, but also a new IF in taskIF/CathxIF.idl, a new entry in
onboard/Makefile, a new log file CathxM12.log, and a new behavior class
in LayeredControl - Cathx.h and Cathx.cc.

The Cathx module produces 3 executables:
 (1) cathxm12    - The driver and direct communication path to the camera.

 (2) cathxServer - The server used by other components in the system,
                   including Layered Control.

 (3) cathxTest   - A test program for the server/driver. The program presents
                   a menu to the user to exercise the functionality.

In addition, there is a log file produced by the driver called CathxM12.log.
The log contains the state of the image capture (0=>"Idle", 1=>"Acquiring")
and the current active profile.

The 'main()' function of the cathxServer can be found in CathxServer.cc file
along with the implementation of the CathxServer class.

The catxm12 driver is started by the cathxServer program. The cathxTest
program, when used, starts the cathxServer program. We assume that the
camera is already powered-up. There is no driver function that switches power
to camera as in the i2MAP project.

2. Configuration

To include the server/driver in a mission, make sure the devices.cfg contains
the line:

cathxServer

The Cathx configuration consists of only the IP of the Cathx camera. As of
version 1.0, the IP was 134.89.32.15 and is hard-coded in _cathxm12.cc. There
is currently no configuration file that would contain the usual things like
IP and the initial camera settings. Fortunately, the settings in the Cathx
camera persist so we can assume that sane profiles already exist when the
unit is powered-up.

3. Functions

As of V 1.0, the Cathx driver (thankfully) only provides the ability to
 (1) start capturing images according to the camera settings
 (2) stop  capturing images
 (3) change the current camera profile to a pre-loaded profile id

The camera profiles are established using a Cathx PC application and uploaded
to the camera prior to use. The driver has no knowledge of the profiles that
reside in the camera, and only refers to them by an integer id. The Cathx PC
app allows the user to give a name to each profile, but there is always a
number associated with the profile name in the app (the number is easily
observed while using the app, right there in the Profile drop down menu). That
unique number is the profile id used by the driver when changing profiles.

4. The Cathx Behavior

The behavior used in mission files is straightforward. An example mission file
demonstrating the recommended use - test_cathx.cfg - resides in this directory.
Read the mission file from the bottom up.

The Cathx behavior class files in Layered Control are named Cathx.h and Cathx.cc.
The cathx behavior suffers from the same issues as the CARL behavior in i2MAP.
That is, consecutive cathx behaviors end up Active at about the same time. The
first one will begin 1st, but the 2nd will begin executing before the 1st is 
complete, resulting in an unpredictable order of execution. However, the cathx
implementation handles this known issue much better.

behavior cathx
{
    id = 1;
    duration = 1;

    capture = 0;
    profile = 3;
}

A cathx behavior in the mission file results in a single message to the cathx
driver containing all the attribute values, rather than a message per attribute.
The example above results in a message saying "Stop capturing images, then set the
active profile to 3". The order that the attributes are listed in the mission file
does NOT matter. The capture attribute is handled by the driver first, then the
profile attribute.

Even when consectutive cathx behaviors are Active at the same time, the messages
sent to the driver arrive in the correct order. The driver handles the messages one
at a time and avoids the jumbled activity we saw in the i2MAP project.

