SmartSampler is an umbrella program for handling the decision making
process for when to take gulper samples.  This README file has both
user info (how to add an algorithm, how to run a test, and some
debugging help) and more detailed program structure (e.g., for
debugging the SS infrastructure).

Algorithms (called DecisionTool's or DT'sin SmartSampler) are
developed under the DecisionTool subdirectory, each with their own
configuration file under $(AUV_CONFIG_DIR).  The basic functionality
is:

1) smartSampler.cfg is read on startup.  Here DT's are enumerated,
   and initial gulper attributions are made.
2) DT-specific configuration files are loaded.  Here each DT tells
   SS which sensors are required, initializes logging mechanism, etc.
3) a periodic callback is set up (default 500ms for real run, 2ms for
   test).  Each callback, SS queries all active DT's, which update
   state and return a T/F firing decision.
4) if any active DT with an assigned gulper requests a gulp or reaches
   a maxwait limit and the system is not in lockout mode, etc, then
   the gulper is fired.


**********  TO ADD AN ALGORITHM  **********

1) Make a new directory under DecisionTool
2) Copy files from SimpleThreshold into your new directory and
   edit to get your algorithm in there.
3) add new DT directory name to DT_LIST in Makefile (here)
4) add DT to model_type enumeration in DecisionTool.hh
5) add DT to factory class generator genDT in DecisionTool.cc
6) add unique configuration file for each instance of DT to be run (in DT subdir)
7) add an item in smartSampler.cfg for each instance of your DT
8) call make install_cfg (here) to copy configuration files to AUV_CONFIG_DIR



**********  TO RUN A TEST  **********

Testing should be done in 3 phases:
1) stand alone SS-only test using smartSamplerTest
   - allows full control over interfaces with fake data input,
     command line interface, etc.
   - starts up the gulper driver, but uses no other drivers
2) simulated connectivity test with supervisor -sim
   - tests server-driver interfaces with the sensor and gulper
     modules, but data are fixed and not useful
3) hardware in the loop test (nothing automated yet)
   - very minimal sanity checks can be done to make sure that the
     basic infrastructure compiles and runs on the vehicle
   - have to avoid connecting to certain sensors, definitely do
     not want to trigger gulpers, etc

To run the stand alone test, compile smartSampler with SELF_TEST=YES.
Make sure the required fake data files can be found locally (same
directory as test run).  May want to change the AUV_LOG_DIR so that 
unique set of log files is generated.  Call smartSamplerTest.



**********  DEBUGGING  **********

SHM semaphores - If you get an error about semaphores in shared memory
    (input or output), it might be the result of improper cleanup.  Try
    removing offending items (e.g., SmartSampler*) from /dev/shmem.

**********  SMARTSAMPLER PROGRAM STRUCTURE  **********

At the top level, the
executables are:

_smartSampler       --> Main driver.
_smartSamplerServer --> Task interface.
_smartSamplerTest   --> A command-line test program.


OBJECTS DEFINED IN THIS DIRECTORY:

SmartSampler --> Instantiates various DecisionTool's (see same-named
                 subdirectory) based on configuration file.  Runs as a
                 periodic task, choosing whether or not to fire
                 gulpers based on the algorithms loaded.

SmartSamplerServer --> External interface for SmartSampler.

SmartSamplerInput --> Command queue for requests from server to
		      driver.

SmartSamplerOutput --> Shared memory interface from driver to server.

SmartSamplerExceptions --> Right now there's just a load error for any
		       problems that occur while loading config.


SUPPORTING FILES:

ConfigTable --> Support for loading a config file which contains a
	    table of arbitrary dimensions (fixed in constructor).

dtConfigList --> Allows us to load a vector of decision tools.

ssdbg --> Support for context-specific debug messages during testing.


CONFIGURATION FILE:

smartSampler --> Initial gulper allocation, and top level information
	     on DecisionTool's to instantiate.  The information is simple
	     for each DT:
	     	     model (algorithm) number
		     DT-specific configuration filename


SUBDIRECTORIES:
DecisionTool --> Algorithms and the factory class to load them.
devices      --> Data and interface managers.
