#
# adcDecode
# author: Mike Risi, Kent Headley
# Copyright 2005 MBARI
#

# Description
adcDecode is a utility for parsing and formatting the output of the 
A/D converters (ADC) used for the MOOS mooring power and optical 
subsytems.

The ADCs sample selected channels at 4 Hz, placing the data into
binary files organized by channel. The file extension is used to 
indicate the channel number, and the file name is a simple index
(1 based), which is incremented when the file reaches 2MB in size.

adcDecode allows the user to read these files and format their output.

# Use Notes
Used without options, adcDecode creates output in the same format as
bin2ascii, upon which adcDecode is based.

When compiled for Win32 under Cygwin, adcDecode requires that
cygwin1.dll be in the path environment variable. If running adcDecode
on a Windows computer without Cygwin, make sure that cygwin1.dll is
installed and in the path.

adcDecode adds a number of features to bin2ascii:

  usage: adcDecode [-cdgnNopqsSt] [logfile]
  options:
   c     : include channel in output record
   C     : do NOT include calibrated value in output record
   g     : include gain in output record
   n <N> : print every Nth record
   N     : include total samples in output record
   o     : include offset in output record
   p     : include period in output record
   r     : include raw counts in output record
   s     : suppress all headers after the first
   S     : suppress all headers
   t     : include time in output record
   q     : disable verbose output

  Examples:

  process file 1.002, process every 1024th sample, Suppress headers, 
  output format: time,channel,calibratedOutput:
	  adcDecode -Sqtcn 1024 1.002

  process file 1.002, process all samples, Include first header only,
  output format: time,channel,gain,offset,rawOutput:
	 adcDecode -sqtcCgor 1.002

# timesync.log
   The timesync.log is a log containing two timestamp columns.  
   The first column is the persistors clock in seconds since the 
   epoch and the second is what ever argument is passed in via the 
   "LOG TIME" command.  The siam serialADC driver occasionally 
   calls the "LOG TIME" command and hands it the seconds since the 
   epoch according to the moorings clock.  This was done so in order
   to track clock drift between the two clocks.  This was done instead of
   synchronizing the mooring and persistor clocks, because when the
   system was initially deployed, it was not clear how much clock
   drift there would be on the mooring clock.

# binary file format
The ADCs produce binary files containing 2MB bins of 4 Hz data. The data
files are names according to bin and channel (<bin>.<channel>), e.g.,
1.002 is bin 1 of channel 2.

The data is written to the output file in 4096-sample blocks, each beginning 
with a header into the data file, defined in log_hdr.h:

typedef struct
{
    long adc_chan;      /* AdcChannel producing the data        */
    long sample_period; /* milliseconds                         */
    long start_time;    /* seconds since 1970                   */
    long total_samples; /* number of sample after header entry  */
    float cal_gain;     /* calibration gain                     */
    float cal_offset;   /* calibration offset                   */
} LogFileHeader;

After the header, raw ADC counts are stored as 16-bit integers in 
*big-endian* format (requiring byte swapping for Win32).
 
When the file reaches the maximum bin size (2MB), output is continued in a new file.

Thus the binary file structure looks like this:

    [header [<adc_chan><sample_period><start_time><total_samples><cal_gain><cal_offset>]
    [sample 1]
    [sample 2]
    ...
    [sample 4096]
    [header [<adc_chan><sample_period><start_time><total_samples><cal_gain><cal_offset>]
    [sample 1]
    [sample 2]
    ...
    [sample 4096]
    [header [<adc_chan><sample_period><start_time><total_samples><cal_gain><cal_offset>]
    ...

# Questions
Q: Is it accurate to create timestamps for each sample by assigning the header time to the first 
sample and incrementing it by the sample period for each subsequent sample?

A: Whether it is accurate or not, it is the only method that exists.  The bin2ascii utility calculates 
the number of samples that are missing or extra based on the timestamp of the first and last sample. 
The sample discrepancy gives you an idea of how well each particular file did.  The logging was tested 
using a signal generator producing a sine wave and the logger was perfored adequately.