TDWR Ethernet Broadcast to IRIS RAW Product Converter
              Revised 2 February 2006

1. Basic Operation Description

This note explains the operation of the software that converts
TDWR eithernet broadcast data into IRIS RAW products.  The 
software is divided into two tasks, mainly:

tdwr_reading_task
raw_create_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 /var/spool/vaisala-io/volume directory.  Immediately
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 /var/spool/vaisala-io/raw directory.

In the meantime, an IRIS input pipe monitors the 
/var/spool/vaisala-io/raw directory, and when a raw product appears 
there, it will read it in and insert into the product
inventory.  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 scan, 
followed by 16 doppler scans.  Likewise, the hazardous scan
consists of a low prf scan followed by 30 doppler scans.  The
TDWR to IRIS converter 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 edited reflectivity data is 
mapped to the IRIS "Z" data type.  The TDWR edited 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
edited width data is mapped to the IRIS "W" data type.

2. Configuration

The two 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.conf", but can be any unix filename.  Please
place it in the /etc/vaisala/irisrda directory.  The configuration 
file is of the following format:

LOG 1
TDWR lan1 10000
IRIS tms_cen1 30725 /srv/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 argument 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 ".log" extension.  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 
eithernet 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 is unused currently.

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.

To configure the input pipe, use the setup program.  Press the 
"Input" button.  Increase the number of input devices by 1.  
Scroll down to the new input device.  Set it as follows:

         Menu alias: TDWR-In
  Pipe program name:
   Source directory: /var/spool/vaisala-io/raw/
Command line syntax: Pathnames
Notification scheme: Polling

Be sure to create the /var/spool/vaisala-io/raw directory and set the
owner to operator.

3. Source code location

This code is an optional extra charge feature.  It is not installed
automatically as part of a normal installation.  To install it, 
run the install program and press the 3 buttons to install Source,
Headers, and Objects.  The source code will then be found in the
/usr/sigmet/utils/tdwr directory.  To compile it, please follow
the instructions in the IRIS Programmer's Manual to configure
the development environment.  Then cd to that directory and type
"make clean", then "make".  Then move the tdwr.conf file to your
${IRIS_CONFIG} directory.  You may have chosen to install your
IRIS at a different root point.  In that case, you will need to
change the tdwr.start script.

If you wish to make changes, please copy this directory to your
development tree at: /home/operator/sigmet/utils/tdwr.  This will
prevent it from being replaced with a future IRIS upgrade.  You
will need to change the tdwr.start script to reference the new
location.  Please send source code changes made to support@sigmet.com.

4. Starting and stopping

To manually start the 3 programs, run the tdwr.start script.
To see if they are running type:

ps -aef | grep tdwr

To manually stop the 3 programs, kill them using the PID
shown in the ps command.

To debug problems, edit the tdwr.conf file to set "LOG 1", then
kill and restart the programs.  You can then examine the log files.


4.1 Automatic Startup on Linux

The script used to start up miscellaneous small programs after
system boot time is "/etc/rc.d/rc.local".  To start the TDWR
to IRIS conversion utility automatically at bootup,
enter a line such as the following at the end of this file:

su - operator -c "/usr/sigmet/utils/tdwr/tdwr.start 1>/dev/null 2>/dev/null&"


4.2 Automatic Startup on HP-UX

On HP systems running the conversion software, 
the kernel 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 kernel parameter.

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 "/usr/sigmet/utils/tdwr/tdwr.start 1>/dev/null 2>/dev/null&"

