Changes between Initial Version and Version 1 of grf2ew

03/19/12 17:52:10 (10 years ago)



  • grf2ew

    v1 v1  
     3= [wiki:Earthworm Earthworm] Module: grf2ew = 
     4'''Contributed by: ''' 
     6== Function == 
     7NetDas Digitizers Earthworm feed via direct connection to GRF server. (Solaris, Linux, Windows) (new in EW v7.2) 
     9== Details == 
     10=== Overview === 
     12GRF2EW 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. 
     14GRF2EW requires Earthworm version 6.1 or later and is currently available on Solaris, Linux, and Win32 platforms. 
     16GRF2EW 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]. 
     18=== Running GRF2EW === 
     20GRF2EW 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. 
     22A simple help screen is available by specifying the -h option: 
     24Usage: grf2ew [-hdc] [-s ip_addr[:port] | -f input_file] 
     25              [-t seconds] [-r output_ring] [-H seconds] 
     26              [configuration file] 
     28   -h  Help display. 
     29   -d  Debug logging. 
     30   -c  Apply sampling rate corrections (No). 
     31   -s  IP address and port number to connect to for input data. 
     32          port number defaults to 3757 if not otherwise specified. 
     33   -f  File to read for input data. 
     34   -t  Socket read timeout in seconds. (30) 
     35   -r  Output ring for TRACE_BUF messages. (WAVE_RING) 
     36   -H  Heartbeat interval in seconds. (10). 
     38The configuration file argument defaults to './grf2ew.d' if not otherwise specified. 
     39[] = optional, () = default, | = mutually exclusive.\ 
     41All of these command line options are equivalent to their corresponding entries in the configuration file. 
     43=== Driving GRF2EW with startstop === 
     45In 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: 
     49and the executable: 
     53Edit 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: 
     55# startstop.d 
     57nRing               1 
     58Ring   WAVE_RING 1024 
     60MyModuleId        MOD_STARTSTOP 
     61HeartbeatInt      15 
     62MyPriorityClass   Normal 
     63LogFile           1 
     64KillDelay         10 
     66Process          "grf2ew grf2ew.d" 
     67PriorityClass     Normal 
     68ThreadPriority    Normal 
     69Display           NoNewConsole 
     71Process          "wave_serverV wave_serverV.d" 
     72PriorityClass     Normal 
     73ThreadPriority    Normal 
     74Display           NoNewConsole 
     76Process          "heli_ewII heli_ewII.d" 
     77PriorityClass     Normal 
     78ThreadPriority    Normal 
     79Display           NoNewConsole 
     82Once things are properly configured, startstop will drive grf2ew along with all other Earthworm modules. 
     84=== Configuring GRF2EW === 
     86The 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. 
     88The 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. 
     90The 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 '#'. 
     92The file is made of two basic groups of entries: 
     94 * '''Server''' - This group specifies the server that GRF2EW will connect to as a client. 
     95 * '''Earthworm''' - This group defines various Earthworm parameters. 
     96Throughout the example configuration file, the default values for each entry are show in end-of-line comments inside parentheses. 
     98=== The 'Server' group === 
     100The server group defines the source server that the program will connect to. This group contains two keywords: 
     102# Copyright (c) 2000-2007 - DAQ Systems, LLC - All rights reserved. 
     103# Configuration file for grf2ew version 1.3.8 or later 
     104# Defaults for each entry are shown in () 
     106# The logging group is now deprecated as logging in now performed  
     107# using the Earthworm logging facility. 
     109# GRF server settings... 
     110Server { 
     111    Endpoint       # GRF server endpoint to connect to 
     112    ReadTimeout       10                # Socket read timeout in seconds (10) 
     115==== The 'Endpoint' entry ==== 
     117This 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. 
     119An 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, '' is equivalent to ''. 
     121==== The 'ReadTimeout' entry ==== 
     123This 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. 
     125=== The 'Earthworm' group === 
     127This group is used to specify the parameters of the Earthworm system. It has seven keyword entries: 
     129# Earthworm settings... 
     130Earthworm { 
     131    Ring              WAVE_RING         # Destination ring for TRACEBUF messages. (WAVE_RING) 
     132    ModuleName        MOD_GRF2EW        # Our module name. (MOD_GRF2EW) 
     133    InstallationID    INST_WILDCARD     # Installation identifier (INST_WILDCARD).  May be entered 
     134                                        #   as a lookup string or decimal value 0-255.  If the  
     135                                        #   environment variable EW_INSTALLATION is defined, its  
     136                                        #   contents are used.  This configuration entry  
     137                                        #   overrides the environment variable setting. 
     138    Heartbeat         15                # Heartbeat interval in seconds. (10) 
     139    CorrectRate       No                # Apply sampling rate corrections?  Yes or (No). 
     140    MinTimeQuality    0                 # Drop data packets with time quality less than this value.  
     141                                        #   0=Unknown, 1=Bad, (2)=Poor, 3= Good, 4=Very good. 
     142    MessageFormat     TRACE_BUF2        # Output message format: TRACE_BUF or TRACE_BUF2. 
     145==== The 'Ring' entry ==== 
     147This 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. 
     149GRF 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. 
     151==== The 'InstallationID' entry ==== 
     153The 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. 
     155At 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. 
     157==== The 'ModuleName' entry ==== 
     159This the Earthworm module name used to identify the GRF2EW program. This module name must be defined in your earthworm.d file. 
     161==== The 'Heartbeat' entry ==== 
     163This entry is used to specify the interval in seconds at which the GRF2EW program will generate heartbeat messages to the output ring. 
     165==== The 'CorrectRate' entry ==== 
     167Use this entry to specifiy whether GRF sampling rate corrections should be applied as messages are created. 
     169==== The 'MinTimeQuality' entry ==== 
     171Use 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. 
     173==== The 'MessageFormat' entry ==== 
     175Use this entry to specify the output message format. TraceBuf2 messages will contain the default location code ('--'). 
     179== Helpful Hints ==