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.
