wiki:grf2ew
Last modified 9 years ago Last modified on 03/19/12 17:55:25

Earthworm Module: grf2ew

Contributed by:

Function

NetDas Digitizers Earthworm feed via direct connection to GRF server. (Solaris, Linux, Windows) (new in EW v7.2)

Details

Overview

GRF2EW is a simple GRF client application that converts GRF data packets to Earthworm TraceBuf or !TraceBuf2 messages and writes them to an Earthworm transport ring. The program also generates heartbeat messages at a user specified interval. The program is controlled primarily through an ASCII configuration file but it also accepts various command line options.

GRF2EW requires Earthworm version 6.1 or later and is currently available on Solaris, Linux, and Win32 platforms.

GRF2EW has been developed as a component of the GRF Tools Suite, a collection of tools for the routine processing of GRF data. More information about the GRF and the GRF Tools Suite is available at the GRF Home Page. Acquisition systems that employ the GRF are available from DAQ Systems.

Running GRF2EW

GRF2EW is invoked from the command line by typing grf2ew and pressing return. However, most Earthworm users will likely use the startstop program to control operation of the program along with other Earthworm modules. We will cover the configuration of the startstop program below.

A simple help screen is available by specifying the -h option:

Usage: grf2ew [-hdc] [-s ip_addr[:port] | -f input_file]
              [-t seconds] [-r output_ring] [-H seconds]
              [configuration file]

   -h  Help display.
   -d  Debug logging.
   -c  Apply sampling rate corrections (No).
   -s  IP address and port number to connect to for input data.
          port number defaults to 3757 if not otherwise specified.
   -f  File to read for input data.
   -t  Socket read timeout in seconds. (30)
   -r  Output ring for TRACE_BUF messages. (WAVE_RING)
   -H  Heartbeat interval in seconds. (10).

The configuration file argument defaults to './grf2ew.d' if not otherwise specified.
[] = optional, () = default, | = mutually exclusive.\

All of these command line options are equivalent to their corresponding entries in the configuration file.

Driving GRF2EW with startstop

In order to use the startstop program to drive GRF2EW you will need to create a configuration file (see below) in your Earthworm parameters directory and ensure that the grf2ew.exe executable to the Earthworm bin directory. Typically, the configuration file will be named:

%EW_HOME%\params\grf2ew.d

and the executable:

%EW_HOME%\bin\grf2ew.exe

Edit the startstop_nt.d file and add the grf2ew module. Below is an example fragment of this file that runs the grf2ew, wave_serverV, and: heli_ewII modules:

# startstop.d

nRing               1
Ring   WAVE_RING 1024

MyModuleId        MOD_STARTSTOP
HeartbeatInt      15
MyPriorityClass   Normal
LogFile           1
KillDelay         10

Process          "grf2ew grf2ew.d"
PriorityClass     Normal
ThreadPriority    Normal
Display           NoNewConsole

Process          "wave_serverV wave_serverV.d"
PriorityClass     Normal
ThreadPriority    Normal
Display           NoNewConsole

Process          "heli_ewII heli_ewII.d"
PriorityClass     Normal
ThreadPriority    Normal
Display           NoNewConsole

Once things are properly configured, startstop will drive grf2ew along with all other Earthworm modules.

Configuring GRF2EW

The configuration file allows you to configure and control all aspects of the programs behavior. This simple ASCII file can be edited using your favorite editor.

The name of the configuration is passed as an argument on the command line at program startup. It is an Earthworm convention to give module configuration files an extension of .d and and store them in the params directory. Therefore the default configuration filename is grf2ew.d and it will be searched for in the %EW_HOME%/params directory.

The configuration file is made up of keywords followed by an entry. Some keywords define groups of entries and curly braces {} are used to delimit these groups. White space characters and/or commas separate keywords and entries. Comments may appear anywhere in the file and always begin with a pound sign '#'.

The file is made of two basic groups of entries:

  • Server - This group specifies the server that GRF2EW will connect to as a client.
  • Earthworm - This group defines various Earthworm parameters.

Throughout the example configuration file, the default values for each entry are show in end-of-line comments inside parentheses.

The 'Server' group

The server group defines the source server that the program will connect to. This group contains two keywords:

# Copyright (c) 2000-2007 - DAQ Systems, LLC - All rights reserved.
# Configuration file for grf2ew version 1.3.8 or later
# Defaults for each entry are shown in ()

# The logging group is now deprecated as logging in now performed 
# using the Earthworm logging facility.

# GRF server settings...
Server {
    Endpoint          192.168.1.5       # GRF server endpoint to connect to
    ReadTimeout       10                # Socket read timeout in seconds (10)
}

The 'Endpoint' entry

This entry is used to specify an upstream server endpoint that will be connected to as a client. The program will maintain this connection for the life of the program.

An endpoint may be specified as an IP number in dotted decimal form or as a domain name. The port number may be specified by appending a colon (:) followed by the decimal port number to the address. If no port is specified, the default port (3757) is used. For example, '192.168.1.1' is equivalent to '192.168.1.1:3757'.

The 'ReadTimeout' entry

This entry is used to specify the timeout value in seconds for upstream client socket connections. If the network connection to the server is very slow or high latency, you may need to increase this value. Under normal operating conditions, the default value of 30 seconds should be appropriate.

The 'Earthworm' group

This group is used to specify the parameters of the Earthworm system. It has seven keyword entries:

# Earthworm settings...
Earthworm {
    Ring              WAVE_RING         # Destination ring for TRACEBUF messages. (WAVE_RING)
    ModuleName        MOD_GRF2EW        # Our module name. (MOD_GRF2EW)
    InstallationID    INST_WILDCARD     # Installation identifier (INST_WILDCARD).  May be entered
                                        #   as a lookup string or decimal value 0-255.  If the 
                                        #   environment variable EW_INSTALLATION is defined, its 
                                        #   contents are used.  This configuration entry 
                                        #   overrides the environment variable setting.
    Heartbeat         15                # Heartbeat interval in seconds. (10)
    CorrectRate       No                # Apply sampling rate corrections?  Yes or (No).
    MinTimeQuality    0                 # Drop data packets with time quality less than this value. 
                                        #   0=Unknown, 1=Bad, (2)=Poor, 3= Good, 4=Very good.
    MessageFormat     TRACE_BUF2        # Output message format: TRACE_BUF or TRACE_BUF2.
}

The 'Ring' entry

This entry is used to specify the Earthworm ring that GRF2EW will attach to and write TraceBuf or !TraceBuf2 messages. The startstop program will create this ring as specified in your startstop.d configuration file.

GRF names are copied to Earthworm SCN names in the output TraceBuf or !TraceBuf2 messages. Note that the station name is limited to seven characters in TraceBuf messages so you should carefully choose GRF station names to avoid truncation in the conversion process.

The 'InstallationID' entry

The installation identifier may be specified as either a string that will be looked up in the earthworm_global.d file, or an unsigned integer value in the range 0-255. This entry defaults to 'INST_WILD', which resolves to 0.

At program startup, installation identifier is set to the default value. The environment is then searched for a variable named 'EW_INSTALLATION' and if found, the installation identifier is set to its value. If the 'InstallationID' entry is then found in the configuration file, the installation identifier is set to its value overriding the environment variable setting.

The 'ModuleName' entry

This the Earthworm module name used to identify the GRF2EW program. This module name must be defined in your earthworm.d file.

The 'Heartbeat' entry

This entry is used to specify the interval in seconds at which the GRF2EW program will generate heartbeat messages to the output ring.

The 'CorrectRate' entry

Use this entry to specifiy whether GRF sampling rate corrections should be applied as messages are created.

The 'MinTimeQuality' entry

Use this entry to specify the minimum acceptable GRF time quality. If data are encountered with a time quality less than the specified value, those data are not converted and sent to the output ring.

The 'MessageFormat' entry

Use this entry to specify the output message format. !TraceBuf2 messages will contain the default location code ('--').

Helpful Hints