# Earthworm Modules:
GRF2EW Configuration

(Last Revised 11 November, 2007)

## 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 ('--').

Module Index | GRF2EW Overview

Contact: robert@banfill.net