This HOWTO describes the steps to set up files for to use
in determining a  heading correction for VmDAS ADCP data.
Examples are from POSMV, Seapath, or Ashtech headings and gyro
headings.

You can only do this if you have a gyro signal going directly 
into the deck unit (as a synchro input).  The gyro data must 
be extracted from the ENS files.

CAVEAT: Although there is quality control available on a
message-by-message basis, additional sanity checks are not 
performed. This is just a framework to get you started, 
though under many circumstances it is enough.

NOTE ALSO: loss of GGA serial data can result in bad "UTC" timestamps.
This complicates matters.  The PC time may be the only one that is 
monotonic, but it probably doesn't match UTC under those conditions.  


THE KEY: you need to get gyro and "other" (ashtech, seapath, or posmv) 
headings on the same time base, to within about one second, to 
determine the heading correction on this time base.  After you have the 
heading correction for that time base, then you can alter it so it is UTC.



Overview:

(1)  (This file)

     NMEA messages logged by VmDAS are parsed and stored
     as binary files ("rbin suffix") which can be read directly by
     matlab.

     This step may require a couple of minutes per cruise for each 
     NMEA string decoded.  If using ensgyro2rbin, several tens of 
     minutes or an hour may be required per  cruise

(2) Load the data from both heading devices into matlab.   Quality 
    control is used to edit out bad points for the gps-aided 
    device. Timestamps are obtained from the database and are 
    used to create a file with decimal days and reasonable (if 
    not good) heading corrections  for the gyro.

(3) Apply the rotation and rerun the navigation and calibration 
    steps.


How To Do It:
NOTE: see TRAPS AND PITFALLS (at the bottom)

(0) Go to the cal/rotate subdirectory of your ADCP processing 
    directory.  Make a new directory called "rbin" and go into 
    that directory (chdir or cd)

(1) Make sure you use the correct switches to indicate that
    the NMEA messages were gathered with that other acquisition 
    system.

    (1a) Get the GPS-aided headings:

    For instance,     
    If $sourcedir is 
       /mnt/vmdas_disk/vmdas_data_archive/osdata/knorr075/transit

    for Ashtech data in N2R files, run:
      serasc2bin.py -rv -y 2003 -t vmdas -c 'last' -m adu $sourcedir/*N2R

    for Seapath data in N2R files, run:
      serasc2bin.py -rv -y 2003 -t vmdas -c 'last' -m psxn23  $sourcedir/*N2R

    for POSMV data in N2R files, run:
      serasc2bin.py -rv -y 2003 -t vmdas -c 'last' -m pmv $sourcedir/*N2R

    (1b) get the gyro headings from the ENS files into rbin files
    (NOTE: Do not use ENR or ENX)
    
    in matlab:
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% begin matlab code %%%%%%%%%%%%%%%%%%%%%%%%%%
    
    %% USER EDITS THIS SECTION:
    ensdir = ...
     '/mnt/vmdas_disk/vmdas_data_archive/osdata/knorr075/transit';
    %% end of section for user to edit

    ensfiles = dirs(fullfile(ensdir,'*.ENS'));
    
    for filei = 1:length(ensfiles)
      filename = ensfiles(filei).name
      ensgyro2rbin(os, fullfile(ensdir,filename));
    end
    %%% end matlab code  %%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


    If you see messages like this:

    WARNING: bad navigation data likely at ensemble 1171 (2003/09/08 22:08:58)

    It is an indication that VmDAS had a problem with the time
    correction for that ensemble.  Don't worry about it unless they
    occur several times per 300-second enseble (or more)

    If you see a figure pop up and lots of messages like this:

    WARNING: correcting time by 3652 seconds

    It indicates the VmDAS computer is having its time reset during
    data acquisition.  This is a serious pain. Email me
    (hummon@hawaii.edu) if you are serious about continuing.  It's not
    worth documenting how to procede because at this point, every case
    is different.  Essentially what you have to do is line up the
    time-stamps of the two heading sources, (gyro and "other"), but
    one or both may jump forward or backward in time.
    
    See "heading_correction_badtimestamps.txt" for more suggestions

(2) Read in the rbin files and get a quality mask for the gps-aided
    heading device.  Assuming you are in the cal/rotate directory and 
    have made your rbin files in cal/rotate/rbin, edit and run
    "mk_ensgyrodh.m".  That file should have been dropped in your
    cal/rotate directory by adcptree.py.  If you have no time-stamp
    problems, and if you are using ashtech, seapath, or posmv, it might
    work.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

see example matlab code to actually generate the correction file

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The most common sources of failure are 
- incorrect paths (to ENS and N2R files)
- incorrect or inconsistent yearbase (serasc2bin.py and ensgyro2rbin.m must
            both have correct yearbase)
- ENS files are sorted in ascii order; that may not match time order.
- If you have you have timestamp problems (time jumps backwards), mk_gyrodh will
            save the gyro and other data to disk as gyrodh_data.mat.  You must load
            this manually and sort out your timestamps by whatever means are 
            necessary.  An example is given in "heading_correction_badtimestamps.txt:
- another message type might be "prdid"; that is OK; just specify "rdi" as the
            message name