7.7.41. ue4_doc.txtΒΆ

UE4.EXE
User exit program written for RDI DAS 2.48.
Author: Eric Firing, University of Hawaii
First version: August 11, 1994
Current version: December 10, 1999

Documentation Table of Contents:
1. FUNCTIONS:           What ue4 does.
2. INSTALLATION:        How to install ue4.
3. CONFIGURATION:       The configuration file: ue4.cnf
4. OPERATION:           Data inputs, screen messages.
5. DATA OUTPUTS:        Output formats: files, serial output
6. USER BUFFER:         Format of data stored in pingdata file
7. DATA DUMPING:        How to view the user buffer data
8. COMPILATION:         Notes on compilation
A. HISTORY:             Notes from various releases



---------------------------------------------------------------
1. FUNCTIONS:           What ue4 does.
---------------------------------------------------------------

1)  At each ping (about once per second), calculate the
velocity of the ship relative to the average of the water in
a reference layer.  This will be called the ship-reference
velocity.  It is in geographic coordinates.

2)  At each ping, filter this ship-reference velocity with a
mild exponential filter, and display it.  Optionally
transmit this information and the heading in a "speed log"
message, NMEA-style format, via a serial port.

3)  At the beginning (ping 2) and the end (just before
writing the ensemble out to disk), grab the latest position
fix, parse it, and store it.  Positions can be obtained from
either or both of two NMEA GGA message sources, one of which
may be an Ashtech 3DF.  One of these sources must be
designated the primary one, the other the secondary.  Both
are stored in the user buffer, but only the primary fixes
are used to calculate the ship's velocity over the ground.
This velocity and the end-of-ensemble position are stored in
the pingdata "loran" structure and are used for displaying
the velocity profile relative to the "nav device", if that
option is selected in the DAS.

4)  Optionally transmit the full ensemble data structure out
through a serial port.

5)  Optionally keep the PC clock synchronized with time from
the fix messages.  This is done by comparing the PC clock to
the gps message time at the start and end of each ensemble.
If these offsets are sufficiently large, and if the two are
sufficiently close to each other, then the PC clock is reset
accordingly 10 pings into the next ensemble.

6)  Receive $PASHR,ATT messages from an Ashtech 3DF, edit
them, calculate means and standard deviations, and store the
results in the user buffer.  The primary variable of
interest is the gps heading minus the gyro heading.

7)  Optionally write raw binary amplitude and/or spectral
width data, together with an auxiliary ascii file that provides
navigation and indexing info for the binary files.

8) Optionally "pat the watchdog"--send a signal to the
watchtsr.exe watchdog timer, so that it knows the ADCP is
still operating and does not have to reboot the PC.

9) Optionally receive a heading string through a serial
port, and insert the heading in the DAS data space,
overwriting any heading data (or garbage) from the profiler.

10) Optionally print a warning on the screen if the standard
deviation of the heading during an ensemble is below some
threshold, indicating that either the ship is at the dock
(no problem), or the heading input may be locked up.

---------------------------------------------------------------
2. INSTALLATION:        How to install ue4.
---------------------------------------------------------------

UE4 must be set up and loaded via the UX user exit menu in
the DAS.  It should be installed as exit N (not one of the
numbered exits) with entry points 4, 5, and 9.  The
interrupt number should not matter so long as it does not
duplicate that of another loaded user exit.  The full path
name (either absolute, or relative to the current working
directory) of UE4.EXE must be specified. Make sure the user
exit is enabled in both places on the UX menu.

The second place where the user exit must be installed is in
the Data Recording menu.  Set RB to 192 (bytes of user
buffer to record). A reminder to do this, including the
correct number of bytes, is printed to the screen when the
user exit is loaded (after hitting P in a DAS menu).

The third place to check is the Serial Device menu.  The
serial port numbers used by UE4  MUST NOT APPEAR
in the Serial Device menu.  Any DAS serial communications
functions must be via other ports, with separate
interrupts--no sharing.  UE4 loads and uses its
own serial device drivers.

The fourth setup item is the CONFIG.SYS file, used by DOS at
boot time.  It must contain DEVICE = <path>ANSI.SYS, where
<path> is the location of the ANSI.SYS file.  UE4 uses
the ANSI.SYS console device driver for screen output.
(Recall that the DAS also requires DEVICE =
<path>GPIB.COM.)

---------------------------------------------------------------
3. CONFIGURATION:       The configuration file: ue4.cnf
---------------------------------------------------------------

Once a satisfactory setup has been arranged through the UX
and DR menus, the DAS configuration should be saved as the
default. Then the user exit setup will be loaded
automatically on startup, and it should not be necessary to
use the UX menu again.  Note that the DAS configuration is
stored in more than one file, not just the ASCII main
configuration file. In particular, the EXIT.CNF binary file
contains the name of the user exit program. All the files
should be present when ADCP is loaded.

UE4 itself is configured via an ASCII configuration file,
similar to the control files used for most CODAS ADCP data
processing programs.  Like the latter, the UE4 configuration
file may contain free-form comments of any length, delimited
by the /* */ pair used in C programs.  One slight
difference: in the UE4 configuration file, the /* and */
delimiters must themselves be separated from all other text
by white space.  (This change was made to keep the user exit
code small and fast.)  In other words, /* this is */ fine,
but /*this is NOT ok*/ because the comment delimiters are
not separated from the text.  Also, note that comments may
NOT be nested.

The UE4 configuration file MUST be named UE4.CNF, and it
MUST be located in the default directory when the ADCP
program is run.  Otherwise, UE4 will fail to find its
control file.  The control file must be read whenever UE4 is
loaded, which is any time pinging is started via the P
command in a DAS menu.

The configuration file consists of keywords, sometimes
alone, sometimes followed by parameters.  Keywords and
parameters must be separated by whitespace, but otherwise
the formatting is completely free--nothing is line-oriented.
Keywords with "=" at the end (the "=" is PART of the
keyword) must be followed by a number; those with ":" at the
end are followed by a character or string; and those ending
in a letter are not followed by any parameter at all.  The
keyword "end" is required to end a group of options.
Everything is case-sensitive.

Here is a sample configuration file, with comments.
You can copy the block between the lines to a file named
ue4.cnf and edit it to your requirements.

----------------ue4.cnf starts on next line--------------------
configuration:                /* This keyword is necessary. */
                              /* Use up to three of the
                                 following: set_com1:,
                                 set_com2:, set_com3:,
                                 set_com4:. */
   set_com1:                  /* Use com1 with following params: */
      baud=      4800         /* 300, 1200, 2400, 4800
                                 (=default),9600, 19200 */
      parity:    N             /* N, O, E. Default: N*/
      receive:   nmea_1         /* none, nmea_1, nmea_2,
                                   ashtech_1, ashtech_2,
                                   heading */
      transmit:  speed        /* none, ensemble, speed */
   end                        /* End of com1 setup. */

   set_com2:                  /* Same things for com2. */
      baud=      4800
      irq=       3            /* This is not really needed
                                 for com2, because IRQ 3 is
                                 the default and is highly
                                 standardized.  More
                                 typically, the irq= option
                                 would be used to override
                                 the defaults of 5 and 7 for
                                 com3 and com4,
                                 respectively. */
      parity:    N
      receive:   ashtech_2
      transmit:  ensemble
   end

   set_com3:
      baud=       4800
      receive:    heading
      transmit:   none
   end
   /* keywords for the heading input option */
   heading_format: $HEHRC%lf, /* This is the C-language
                                 "scanf()" format string
                                 used to extract a single
                                 double precision number
                                 from the heading input
                                 string.  It must include
                                 one and only one "%lf".  It
                                 may not include spaces. */
   heading_units=  0.01       /* Scanned heading gets
                                 multiplied by this.  For
                                 example, if heading is in
                                 hundredths ("19230" for
                                 192.3 degrees), set this to
                                 0.01. Default is 1.0 */
   heading_string_offset= 0   /* Usually not needed; default
                                 is zero, meaning the heading_format
                                 begins with the first
                                 character of the string. */
   /* end of heading input options */
   /* Option to monitor heading for lack of variation: */
   warn_bad_heading           /* Include this keyword to enable
                                 the warning; it is disabled by
                                 default. */
   head_stddev_thresh= 0.1    /* Default is 0.1 degrees. */
   /* End of heading monitor options */
   rdi_style_ensemble         /* send ensemble with extra
                                                   characters */
   first_ref_bin= 2           /* zero-based bin for speed log */
   n_ref_bins=   10           /* number of bins to avg for log */
   new_ref_weight= 0.3        /* number between zero and 1; weight
                                 given to new ref layer velocity
                                 in exponential filter smoothing
                                 of reference layer, and hence of
                                 ship's velocity, for display of
                                 navigation-referenced currents */

   watchdog                   /* Include if and only if you
                                 have installed watchtsr.exe
                                 and set it up as described
                                 in its associated docs. */
   /* PC clock correction options */
   correct_clock              /* Include this and the
                                 following only if the
                                 automatic clock reset
                                 function is desired.   */

   min_correction= 2          /* Reset the clock only if it
                                 is x or more seconds off */
   max_correction= 32760      /* Don't make any correction
                                 larger than this. */
   max_dt_difference= 2       /* Make a correction only if
                                 the pc-gps difference at
                                 the start of an ensemble is
                                 at least this close to the
                                 value at the end of the
                                 ensemble  */
   init_time                   /* Attempt a time correction
                                  before the first ensemble.
                                  (recommended!) */
   /* GPS attitude parameters */
   max_brms= 0.03              /* Ashtech editing parameters   */
   max_mrms= 0.004
   max_dh_dev= 1               /* Do not accept any gps-gyro
                                  heading difference
                                  exceeding the mean by this
                                  number of degrees.  The
                                  mean is calculated in
                                  20-sample ensembles. */
   max_p_std_dev= 2.5          /* Reject attitudes if the
                                  pitch exceeds the local
                                  mean by this number of
                                  standard deviations. */
   max_r_std_dev= 2.5          /* Same for roll. */
   /* commands for POS/MV and/or Seapath in place of Ashtech: */
   accept_PRDID                /* Include this line to use the
                                  PRDID message. */
   min_GAMS= 2                 /* for POS/MV, set to 0 to accept
                                  all messages, 1 to accept messages
                                  with GPS or GPS/GAMS, and 2 to
                                  accept only GPS/GAMS (default).
                                  Only effective for PASHR message.
                               */
   max_posmv_pstd= 0.1
   max_posmv_hstd= 0.1         /* POS/MV, PASHR message includes
                                  estimated standard deviations of
                                  pitch and heading; these parameters
                                  allow you to set maximum values for
                                  editing.  If using POS/MV, you
                                  MUST set these manually to suitable
                                  values.  If using PASHR,ATT messages,
                                  as from an Ashtech, you MUST OMIT
                                  these messages, otherwise they will
                                  conflict with max_brms and max_mrms,
                                  which use the same variables. */

   /* keywords for writing raw amp, sw, and auxiliary files:  */
   /* Most users will omit these. */
   amp_sw_nbins= 20            /* If present and nonzero,
                                  this gives the number of
                                  bins of raw amplitude
                                  and/or spectral width to
                                  be written to binary
                                  files.  Default is 0
                                  (disabled). */
   amp_subsample= 1            /* Raw amplitude ping
                                  sampling rate; 1 to write
                                  every ping, 2 for every
                                  other ping, etc.  Default
                                  is 5. */
   sw_subsample= 1             /* As above, but for spectral
                                  width */
   amp_sw_drive_path: d:\raw\  /* Drive and path for the raw
                                  files.  Highly recommended
                                  to use a DIFFERENT drive
                                  than for the velocity
                                  data; the raw file data
                                  rate tends to be
                                  staggering.  If omitted,
                                  this defaults to the same
                                  location as the pingdata
                                  files. */
   minutes_per_file= 10        /* Nominal file length in
                                  minutes.  Default is 60.  */
   min_kbytes_free= 2000       /* If the space on the raw
                                  file drive is less than
                                  this amount (kbytes) at
                                  the start of an ensemble,
                                  then raw recording will
                                  stop.  It will start again
                                  at the beginning of the
                                  first ensemble when space
                                  is available.  Default is
                                  2000.  Don't try to make
                                  it small!  Allow plenty
                                  for all the raw data that
                                  will be written during a
                                  single ensemble (e.g. 5
                                  minutes. */
   /* end of raw data recording options */

end                           /* This "end" is necessary. */
-------------ue4.cnf ends on line above----------------------

The sample includes all possible options (at present):

NOTE: you can have only one "nmea_?" option and one "ashtech_?"
option; and of these only one can be "1", the other must be "2".
In other words, the possible combinations are nmea_1 and
ashtech_2, or nmea_2 and ashtech_1.  If there is only one
GGA source, it should be primary: nmea_1 or ashtech_1.  The
Ashtech 3DF is typically not a particularly accurate or
reliable source of position fixes, so if possible, use a
better receiver as nmea_1, and let the Ashtech be ashtech_2.

Most users will not need or want the dr_request_interval=
option; this is retained for convenience on the Moana Wave,
and causes Magnavox 1100 series data requests to be sent out
over whichever port is used for the speed log function, at
intervals of the given number of seconds.

The rdi_style_ensemble option is included for ships such as
the Cromwell, which are set to receive ensembles via a
serial port in the format used by an RDI user exit program.
This begins with a count of the number of characters (as a
decimal 4-character string), followed by 10 ">" characters,
then the actual binary ensemble data, and then 2 extra
characters.  If this option is NOT included, then only the
actual binary data are sent over the serial port. Capturing
this stream then yields a file that is directly readable by
any program that reads the "pingdata" files written by the
DAS.

The first_ref_bin= and n_ref_bins= options control the bins
used for calculating the ping-by-ping speed log output only;
they have no effect on the bin range used by the DAS for
data display, or on any aspect of the recorded data.  Hence
they are needed only if the speed log function is being
used. Setting first_ref_bin= to 1 or 2 is recommended so
that the speed log function will continue to work in shallow
water. The average is taken over all bins in the given range
with "valid" data, so it will yield nothing in shallow water
if the first bin is set too deep.  There is only minimal
error checking on the bin parameters; it is the user's
responsibility to ensure that the bin range for the speed
log calculation is within the range of bins actually
available, as set in the DAS menus.  Note, however, that
first_ref_bin= is 0-based; that is, the first available bin
is 0, not 1.

The options for setting up the com ports should be mostly
self-explanatory, with the help of the comments in the
sample.  If only one com port is needed, then just comment
out or omit the specification for the other port.  Note that
the receive and transmit functions can be quite different;
one can wire the receive line to one device and the transmit
to another (so long as signal ground is common, if the ports
are RS-232). There is relatively little error checking;
specifying an invalid baud rate, for example, will not
generate an error message.

Physical com port specs and requirements:

All com ports must have separate interrupts in the 1-7
range.  This is NOT part of any PC standard.  To the extent
there is a standard, it is that com3 uses the same interrupt
(IRQ 4) as com1, and com4 the same as com2 (IRQ 3).  They
are not even shared--they simply can't be used at the same
time.  So, if you use more than the standard com1 and com2,
you must add your own board and set its interrupt to an
available one, typically 5 or 7.  Watch out for conflicts
with network adapters, which often use 5.  (Generally, for
the sake of simplicity and robustness, I recommend against
having a network enabled in an ADCP DAS PC anyway.) You will
also have to set the IO address.  This is reasonably
standardized for com1-4, and ue4 sticks with the standard:
3f8, 2f8, 3e8, 2e8 for 1, 2, 3, and 4, respectively.  The
ue4 default IRQs are respectively 4, 3, 5, 7.  These you can
change with the "irq=" option.

Some multiple serial port boards, such as those from
Quatech, allow all ports on the board to genuinely share a
single interrupt.  Supporting this would require additional
code in ue4's serial device driver.  I have not done the
necessary programming.  I have also not added the code
required to support the cascaded IRQs (8-15).  The device
driver does support 16550 UARTs, however, and these are
recommended for all serial ports (although RDI's device
driver does not take advantage of them).

---------------------------------------------------------------
4. OPERATION:           Data inputs, screen messages.
---------------------------------------------------------------

The GPS receiver must be set to output $GPGGA
messages as often as possible, preferably once per second.
Other NMEA strings may be present so long as there is always
a $GPGGA string within any 1000-byte interval.  Check that
the GPS receiver is set to output the $GPGGA string with at
least 3, and preferably 4, digits of precision in the
position--some default to 2 digits, which is inadequate.

The Ashtech 3DF, if used, should be set to output the
$PASHR,ATT... message string at least once per second,
preferably twice per second.

If there is a serial heading input, it should be known to be
highly reliable, and should be updated at least once per
second.  Heading messages such as the standard NMEA "$HEHDT"
do not include time tags.  UE4 simply stores the serial data
stream in a circular buffer.  At each ping (exit point 4),
it starts at the end of the buffer (last character received)
and, working backwards, looks for the first complete line
that can be parsed successfully with the given scanf format
string.  It does not mark messages as used; if another ping
comes before another heading message, the old message will
be found and used again.  This is a potential problem only
if the messages are not updated regularly.  For example, if
the heading input simply stops, UE4 will never know it--it
will just keep using the last heading that was received
before the failure.

The heading input function does not write anything to the
screen.  The heading being used is still written by the DAS
itself in the usual place near the upper right.  Just as
with normal synchro input, this number should be monitored
for reasonableness (does it match the ship's compass
repeaters?) and to make sure it is changing, if only by a
tenth or so.

The DAS PC clock should be set to GMT.  If the automatic
reset feature ("correct_clock") is enabled (as I recommend,
unless the DAS PC has some other external mechanism for
keeping its clock in sync with UTC) beware of one
limitation: the correction will not work if the ensembles
are too short, because the clock is not reset until ping
number 10.  To prevent erratic timing on the first few
pings, it is recommended that you use the "init_time" option
so that the PC clock will be set before the start of
the first ensemble.  This will take care of any major clock
shift, and all subsequent shifts should be very small.
Note, however, that clock correction by ue4 is intended for
moderate corrections only; it can't handle more than a few
hours, and it know nothing of the date!

UE4 should run unobtrusively, with little delay to the DAS.
A few messages are written to the screen, so the user can
monitor the receipt of position fixes, and the ping-to-ping
speed of the ship relative to the water.  These messages are
listed by starting row, column position on the screen:

   14,74: "G: SE", where the "G:" is always present, and "S"
   and/or "E" indicate that a gps fix was received at the
   start and/or end, respectively, of the previous ensemble
   (the one displayed on the screen).

   19,57: "U=uu.uu V=vv.vvm/s" shows the speed-log function:
   the velocity of the ship relative to the reference layer,
   slightly filtered, ping by ping.

   24,42: "dt: ttttt,ttttt" gives the integer number of
   seconds of the gps fix time minus the corresponding PC
   time when the fix was received, modulo 1 day.  The first
   number is for the fix at the start of the previous
   ensemble, the second for the fix at the end.  Hence,
   these numbers suggest the number of seconds that should
   be added to the PC clock to correct it.  You can do this
   automatically with the "correct_clock" option.  If you
   prefer manual clock adjustments instead, then I suggest
   that you NOT adjust the PC clock frequently; it is easier
   to leave it alone and make a single correction based on a
   constant drift rate when the data are processed.  Note
   also that the "dt:" numbers could indicate the absence of
   current fixes.  Receivers typically keep repeating the
   last valid fix during intervals when they are not getting
   current fixes.  In this case, the two dt: numbers will
   differ by the length of the ensemble, rather than the
   usual second or two.  I do not expect this to happen,
   however, at least when using an MX4200, because in the
   GGA message there is a status field that indicates
   whether the fix is current.  This is checked by UE4, and
   only current fixes are accepted.

   3,45: "Ash-gyro: xx.x, n= yyy" shows the Ashtech heading
   minus the gyro heading averaged over the PREVIOUS
   ensemble, based on yyy samples.  For the first ensemble
   after the start of pinging, both fields will be zero.

   3,59: "***CHECK GYRO INPUT***" appears if the keyword
   "warn_bad_heading" is in the control file, and the
   heading standard deviation during the last ensemble was
   less than the parameter "head_stddev_thresh=" (default
   0.1).  If it occurs at the dock, this is not a cause for
   concern, of course.

   3,74: " xxx.x" shows the gps heading minus gyro heading at
   each ping for which it is estimated.  If it is not estimated
   on a given ping, there will be dashes in place of the number.
   This display is present only when the ashtech option is
   in use.  Numbers should be displayed at something like the
   slower of the ping rate and the ATT message rate; neither the
   gyro heading estimate at any given ping, nor any ATT message,
   is ever used more than once.

   3,1: "raw: xxxxxx K free of yyyy min" shows how many
   Kbytes of space (xxxxxx) are available on the drive to
   which raw amplitude, spectral width, and auxiliary files
   are being written, and what is the threshold in Kbytes
   (yyyy) below which these files will not be written. This
   message appears only when raw data logging is enabled.

   3,1: "RAW RECORDING STOPPED; OUT OF SPACE" appears in
   place of the message above when available space has
   dropped below the minimum.  If space is subsequently
   freed (for example, if the drive is networked, another
   machine could be used to transfer the files to tape),
   then logging will resume and the previous message will
   be displayed.  Space checking, and cessation or
   resumption of logging, occur only at the start of each
   DAS ensemble.


---------------------------------------------------------------
5. DATA OUTPUTS:        Output formats: files, serial output
---------------------------------------------------------------

a) Raw amplitude and/or spectral width, plus auxiliary:

   File naming: the binary and auxiliary files are opened
   simultaneously.  Extensions are ".amp", ".sw", and ".aux"
   for the respective data types.  The file name is formed
   from UNIX system time in minutes; that is, it is minutes
   since the start of 1970.

   File contents:

      *.aux files start with two header lines, the first
      giving the date and time, the second the values of the
      parameters nbins_aux, nsub_amp, and nsub_amp.
      Then, for each subsample of amp, sw, or both, there
      will be one or two lines:
         If primary navigation data area available, the
         first line will be most current GPS fix ($GPGGA
         message).  If fix data are unavailable, this line
         will be absent.
         The other line consists of 4 decimal integers:
         (1) UNIX system time in seconds (PC clock).
         (2) sequence number of ping within the ensemble.
         (3) offset into the amplitude binary file of the
         current sample, if any; if amplitude was not
         sampled, the offset will be "-1".
         (4) offset into the spectral width binary file, as
         for amplitude.

         example:
---------------13996716.aux starts on next line-------------
Sun Aug 11 22:33:38 1996
bins = 48, amp = 1, sw = 2
$GPGGA,223338,2119.0175,N,15753.1712,W,1,6,01,036,M,002,M*7D
839802818 1 0 -1
$GPGGA,223339,2119.0173,N,15753.1713,W,1,6,01,037,M,002,M*7A
839802819 2 192 0
$GPGGA,223340,2119.0172,N,15753.1715,W,1,6,01,037,M,002,M*73
839802820 3 384 -1
$GPGGA,223341,2119.0170,N,15753.1716,W,1,6,01,038,M,002,M*7C
839802821 4 576 192
$GPGGA,223342,2119.0168,N,15753.1718,W,1,6,01,039,M,002,M*79
839802822 5 768 -1
$GPGGA,223343,2119.0166,N,15753.1719,W,1,6,01,039,M,002,M*77
839802823 6 960 384
---------------------------------------------------------------
      In this example, we are recording 48 depth bins for
      each of the four beams, sampling amplitude every ping
      and spectral width every other ping.

      Note: it is possible for the PC times (e.g. 839802822
      etc.) to be non-monotonic.  When the time correction
      option is enabled, the PC clock may be occasionally be
      corrected, typically by 2 seconds.  This will cause
      apparent jumps in recorded clock time, forward or
      back.

      .amp and .sw files are simple arrays of unsigned
      bytes.  For each sample, there are amp_sw_nbins= bytes
      for beam 1, then the same number for beam 2, for beam
      3, and for beam 4.  Each sample (2-dimensional array
      of bytes) begins at the offset given in the .aux file.
      Successive samples are simply concatenated, so the
      offsets don't really need to be read from the .aux
      file; they are just there for convenience.

b) speed log output

   "$PUHAW,UVH,uu.uu,vv.vv,hh.h" CR LF
      $PUHAW means Proprietary University of HAWaii
      uu.uu (floating point) is velocity east in knots
      vv.vv is velocity north in knots
      hh.h is heading in degrees, 0-360.0
      string is terminated by CR LF (DOS text line termination)

c) ensemble output

   The serial ensemble output consists of the same sequence
   of bytes as appear in the pingdata file, with 2
   exceptions:

      1) In the pingdata file, a new header record is
      generated only when pinging is started ("P" in the DAS
      menu).  In the serial output, every ensemble contains
      a header.

      2) If the "rdi_style_ensemble" keyword appears in
      ue4.cnf, then some bytes are added to the beginning
      and end of each ensemble.  (characters between the
      quotes)
         beginning: "NNNN>>>>>>>>>>"
            NNNN is an ASCII 4-digit string with a count of
            the number of bytes that follow.
         end: "  "
            Two ASCII space characters.

   (See send_ens.c for clarification.)

---------------------------------------------------------------
6. USER BUFFER:         Format of data stored in pingdata file
---------------------------------------------------------------

      typedef struct
      {
         long pc_seconds, gps_seconds;
         double lat, lon;
         float height;
         char dop, nsat, msg_type, spare;
      } GPS_FIX_TYPE;  /* 32 bytes */

      typedef struct
      {
         int dh_mean,   dh_std,  dh_min,  dh_max,
             p_mean,    p_std,   p_min,   p_max,
             r_mean,    r_std,   r_min,   r_max,
             mrms_mean, mrms_std,mrms_min,mrms_max,
             brms_mean, brms_std,brms_min,brms_max;
         int n_att, n_used,
             n_reacq, n_mrms,
             n_brms, n_outlier,
             spare1, spare2;
      } ASHTECH_ATT_STAT_TYPE; /* 56 bytes */

      typedef struct
      {
         int              version,
                          n_samples,
                          s_added,    /* for auto clock correction */
                          spare;
         GPS_FIX_TYPE     fix[4];
         ASHTECH_ATT_STAT_TYPE att;
      } USER_BUFFER_1920_TYPE;

Of the 4 GPS_FIX_TYPE elements: the first two are from the
primary source (e.g. "nmea_1" option), the second
two from the secondary (e.g. "ashtech_2" option).  In each
pair, the first is from the start of the ensemble, the second
from the end.


---------------------------------------------------------------
7. DATA DUMPING:        How to view the user buffer data
---------------------------------------------------------------

The scanping.exe program included with this package (and as
part of the CODAS-based UH ADCP data processing package) can
write the user buffer contents out as a flat ascii file.
Modify the sample control file, scanping.cnt, to list your
pingdata files, and to change file names as needed.  The UB
output file can be loaded into Matlab; then run the m-file
j_names, and you can access the columns of the matrix as,
e.g. "all(:,jsec)" for the column with the time corrections,
"all(:,jf1x)" for the column with decimal degree longitude
from the primary gps source at the start of the ensemble,
etc.

To produce an output file with fewer columns, edit a copy of
ue4_f1.def (and change j_names.m accordingly).  Note that
the FORMAT keyword must be followed by a quoted string
contining a blank space if you want to suppress output of a
given field; if you use an empty string (e.g. ""), you will
get the default output format, which is verbose.  (This is a
limitation of the structure printing system; maybe we will
get around to fixing it some time.)


---------------------------------------------------------------
8. COMPILATION:         Notes on compilation
---------------------------------------------------------------

If you recompile the program, set the Turbo C compiler to
produce 8087 code, not emulation.  Use the small memory
model.  Turn all debugging switches off.  This program has
been tested only with Turbo C 2.0, but I expect it would
compile and run using later Borland compilers with little or
no modification.  See ue4.prj for a list of modules.  Later
versions of TC and BC use different project file formats, so
you will probably have to build your own, or write a batch
or make file.  Some day maybe I will add this to the
package.

There is a possible hitch with using another compiler: the
size of the program might be different.  If the size is
smaller, no problem; if it is larger, then it might no
longer fit in amount of space allocated with the
PARA_TO_KEEP defined in nav.h, and used in memres.c and
ue_main.c.

How PARA_TO_KEEP is estimated:  From the map file, one can
find the total memory required by the code and data: it is
the "stop" entry for _BSS.  Add to this 256 bytes for the
Program Segment Prefix (PSP).  Add enough for the heap and
the stack.  Divide by 16 to get the size in paragraphs, and
that should be the minimum PARA_TO_KEEP.  The heap does not
need to be large; memory allocation is used only in cbuf.c,
and there only to allocate one structure of 14 bytes for
each serial port receive function.  With 3 serial ports,
that is a maximum of 42 bytes.  The stack also can be quite
small. There are no recursive functions, and no large auto
variables.  Large variables such as string buffers are all
static.  The TC default stack of 4k should be more than
enough; 1k would probably do.

---------------------------------------------------------------
A. HISTORY:             Notes from various releases
---------------------------------------------------------------

This user exit program is derived from  ue3.exe.
Thu  08-11-1994
Eric Firing

2000/03/20
Modifications in support of Ashtech alternatives.  PRDID
messages from any source can now be used, but there will
be no quality control--those messages contain only heading,
pitch, and roll, so you have to trust whatever sensor is
sending them.  PASHR messages (to be distinguished from
Ashtech PASHR,ATT and similar Trimble messages) from a
POS/MV will be used if Ashtech messages are not found.
See the description of the control file options, above.

Thu  99/12/09 cbuf.c was modified to simply clip lines that
exceed the buffer size.  This fixes a bug in which incoming
lines longer than the message buffer (132 bytes) would stop the
search for a particular message; for example, the PBN
message from an Ashtech ADU2 could block recognition of a
prior ATT message.

A new routine was added to enable the transmission of raw
data through a serial port.  This is intended to facilitate
the development of a new DAS; it is not for routine use.
Note that the baud rate has to be reasonably high for this
to work. 9600 is at best marginal, and may not work,
depending on the setup.  Because it is not for general use,
the raw data function is not documented further here.

Tue  98/05/19 Incorporated changes made by Teri Chereskin's
people (Matter, Lyn Harris): Nav messages of the form $??GGA
are now accepted, not just $GPGGA as before; and there are
two new control file options to enable checking for lack of
variation in heading, putting a warning on the screen if the
standard deviation of heading during an averaging period is
less than a given threshold.  This is to help detect gyro
interface or related failures that may cause the heading
input to lock at a constant value.

Tue  98/01/20 Removed the old MX1100 series support, and
changed the speed log output format to an NMEA-style.  The
dr_request_interval= keyword in ue4.cnf is **no longer
allowed**.

This release also includes a possibly temporary augmentation
to the aux file recording capabilities, which is otherwise
not yet documented above.  It should have no effect for most
users.

The size of the NMEA message buffer (NMEA_MAX in nmea.c) was
increased from 80 to 160 characters.  Any message longer
than this would stop the process of looking for a GGA
message, so any such long message sent after the GGA would
prevent the GGA from ever being found.

Wed  09-18-1996 Added the ability to receive heading from a
separate serial port and insert it into the DAS data space
at exit point 4.  Added support for 3 ports at a time
instead of 2.  Edited the documentation in several areas in
addition to those relevant to the new capabilities.  New
capabilities, and especially the new serial port, require
more memory: it is now set at 60 K.  There are ways to scale
this back a bit if we need to cram more into the program.

Sun  08-11-1996  Added the ability to write out files with
raw amplitude and/or spectral width.  Note the explanation
of new control file keywords and screen messages.  For
an explanation of the file structure, see section 5 above.

An error in the calculation of the top-of-stack was also
fixed in this version, and the memory allocation was
tightened up.  The present version uses 56K.

Mon  07-01-1996  Added support for Charlie Flagg's watchdog
system, part of his "autoadcp" system written by Joe
Lewkowitz when he was at RDI.  If ue4.cnf contains the
keyword "watchdog", then ue4 will "pat the watchdog" after
every ping.

Added the option "init_time", which causes ue4 to check the
PC clock against time from the GGA messages received by the
primary navigation source before pinging begins, and to
adjust the PC time if necessary.  The parameters that
control the time checking and adjustment are the same as
those used during each ensemble.

Tue  06-27-1995  New, minimally tested version with
flexible support for any 2 of the standard com ports (com1
through com4).  In the control file, just use com3: and/or
com4: the same way as com1: and com2:.  These com ports
specify the IO addresses (1 through 4 are 3f8, 2f8, 3e8,
2e8, respectively) and assign default IRQ assignments (4, 3,
5, 7, respectively).  In addition, the IRQ can be changed
within the com?: setup block with the new option irq=.
However, the IRQ is restricted to be less than 8.  As usual,
IRQs must not conflict.  There is no error checking!

This version is also intended to make use of the 16550 UART
if present.  There is no difference in the code depending
on the type of UART; the setup instruction for the 16550
should have no effect if an 8250 is there instead, and the
interrupt handler loops based on the Line Status Register,
so it should also work with or without the 16550.

Mon  06-26-1995  (1) Fixed a bug that caused repeated time
resets, every other ensemble, when Ashtech was providing the
primary position fix and there was a gap in the Ashtech data
stream.  The problem was that when an Ashtech GGA fix was
not received, the last fix and corresponding PC clock time
were reused as if they were current.  In the case of Ashtech
as the secondary navigation source, this would not have
caused spurious time adjustments, but it would still have
caused repeated fixes in the user buffer.
(2) Changed the message identification requirement to match
"$P????,ATT", so that Trimble messages would be identified
as equivalent to Ashtech messages.  The assumption is that
anything with the ATT part will have the same format, or at
least that all such messages will have formats that can be
parsed in the same way.  Depending on what Trimble (and
others?) do, it may become necessary to recognize individual
vendor's messages and treat them differently.

Wed  05-24-1995  fixed slight bug in ashstat.c
(edit_msg_buf); editing of pitch was based on std dev of
roll instead of pitch.

Modified Wed  11-16-1994  to accept GGA messages that lack
the antenna height field.  This is not optional; no control
file changes are needed.

Modified Sat  10-08-1994  to edit the attitude readings
based on deviations of the pitch and roll from their means,
as calculated in sets of 30 consecutive readings.
Thresholds are given by two new control file parameters:
max_p_std_dev=  and  max_r_std_dev= .  See control file
example below for details.

>>>>>>>This is a user exit program for use with RDI DAS
version 2.48 only; do not try to use it with any other
version.<<<<<<  It can be modified to work with future DAS
versions if necessary, but such modifications require
special information which must be provided by RDI.

Main differences from UE3.exe:
1) The MX4200 raw data port is NOT supported in UE4.
2) Ashtech 3DF attitude ($PASHR,ATT...) and position
($GPGGA...) messages ARE supported in UE4.