TDWR Ethernet Broadcast to IRIS RAW Product Convertor

This note explains the operation of the software that converts
TDWR ethernet broadcast data into IRIS RAW products.   The software
is divided into three task, mainly:

tdwr_reading_task
raw_create_task
iris_send_task

The tdwr_reading_task listens to the TDWR UDP port and reads
TDWR data.  Once a complete radial is received (which may have
been divided up into multiple packets for transmission), the
tdwr_iris_interface task notifies the raw_create_task via IPC
message queue.  The raw_create_task receives the IPC message
and as a result reads the radial in from a shared memory pool
between the tdwr_reading_task and the raw_create_task.  The 
raw_create_task converts each radial of data into IRIS ingest
data format, and when a complete sweep is received (nominally
360 radials), the raw_create_task writes out the ingest data
to disk in the /usr/iris_data/volume directory.  Imeadiately
after writing out the data, the raw_create_task converts the
ingest data into a sweep-by-sweep IRIS raw product and writes
this product to the /usr/iris_data/raw directory.  In the
meantime, the iris_send_task scans the /usr/iris_data/raw 
directory, and when the raw products appears here, the 
iris_send_task will remote copy the raw product to the IRIS
server computer and send a TCP/IP socket notification message
to the same IRIS server.  This process is repeated continuously.

The TDWR performs one of two different scan strategies, mainly
MONITOR and HAZARDOUS.  Both are complete volume scans.  The 
monitor scan currently consists of a single low prf scans, 
followed by 16 doppler scans.  Likewise, the hazardous scan
consists of a low prf scan followed by 30 doppler scans.  The
TDWR to IRIS convertor takes the low prf scan (from either scan
strategy) and produces a single sweep raw product of task name
"SURVEILLANCE".  It then takes each of the remaining doppler 
sweeps and creates a 16 sweep task called "MONITOR" during 
monitor scanning and a 30 sweep task called "HAZARDOUS" during
hazardous scanning.  The TDWR editted reflectivity data is 
mapped to the IRIS "Z" data type.  The TDWR editted velocity 
data is mapped to the IRIS "V" data type.  The TDWR dealiased
velocity data is mapped to the IRIS "Vc" data type.  The TDWR
editted width data is mapped to the IRIS "W" data type.

The three tasks each require a configuration file passed by
name as the first and only command line argument.  The configuration
file is the same for each task.  Currently, this configuration 
file is called "tdwr.dat", but can be any unix filename.  The 
configuration file is of the following format:

LOG 1
TDWR lan1 10000
IRIS tms_cen1 30725 /usr/iris_data/product/
MONITOR 17 1 0.6 0.6 0.6 1.0 2.4 6.0 9.2 13.0 16.8 20.6 24.4 35.5 40.4
  45.3 50.2 55.1 60.0
HAZARDOUS 31 1 0.6 0.6 0.6 2.4 6.05 9.2 13.0 16.8 20.6 24.4 0.6 1.0 28.2
  32.0 35.8 39.6 0.6 2.4 6.0 9.2 13.0 16.8 20.6 0.6 24.4 28.2 32.0 35.8 
  39.6 0.6 1.05

The first line is the "LOG" line.  This line must have an agrument of
either "0" or "1".  "0" implies that no logging will be done.  A "1" 
implies that logging will be done.  If logging is done, each task creates
a file in the /tmp directory which is called by the name of the task,
plus the ".dat" extention.  These logging files contain information
such error conditions that might have been encountered.   

The second line is the "TDWR" line.  This line takes two arguments.
First in the name of the interface which will be listen to for 
ethernet broadcast data.  A command such as "netstat -nr" can be used
to learn the proper interface name.  The second line if the UDP port
on which to listen.  By default, the TDWR system broadcasts on UDP
port 10000.

The third line is the "IRIS" line.  This line tasks three argurments.
First is the name of the IRIS server which will receive the raw product
files via rcp and socket notification.  In this case, tms_cen1.  The
next argument is the TCP port number on which to send the socket 
notification message.  By default, for IRIS this is 30725.  And the
third argument is the directory which the file should be sent to via
rcp.  By IRIS, this is /usr/iris_data/product/ by default.

The fourth line is the "MONITOR" line.  This line takes a variable
number of arguments.  The first argument is the total number of 
sweeps expected in the monitor scan.  In this case 17.  The next 
argument is the sweep number of the low prf scan.  In this case the
low prf scan is the first sweep.  The rest of the arguments represent
the elevation angle for each of the sweeps of the monitor scan, including
the low prf sweep.

The fifth line is the "HAZARDOUS" line.  This line is the same as the
MONITOR line, but represents the information about the hazardous scan.

On systems running the conversion software, the kernal parameter
called "msgtql" should be increased to a minimum of 300.  This
parameter is set to 40 by default on HPUX 10.20 systems.  If this
parameter is not increased, some loss of TDWR radial data may
occur in the conversion to IRIS raw products.  The SAM utility can
be used to modify this kernal parameter.

For convenience, a file called "tdwr.start" has been provided.  Executing
this file will cause each of the three tasks to startup in turn.  Also,
this file can be called at system bootup to automatically start the
tdwr to iris conversion software.  By default, the program that starts
IRIS and any optional utilities at bootup is called "/sbin/init.d/iris_init".
To start the tdwr to iris conversion utility automatically at bootup,
enter a line such as the following into the "start" section of this file:

su - operator -c "/home/operator/tdwr/tdwr.start 1>/dev/null 2>/dev/null&"

Source code an a mini-development environment has been delivered with
the actual executables.  It is not necessary to use the source code,
but none the less, it has been provided in the event that the HKO wishes
to make changes to the program.  The ".c" file, the ".h" files,
and a Makefile have been provided.
