# Earthworm Modules:
slink2ew configuration file

(last revised July, 2013)
Page Index:
1. Functional command listing
2. Alphabetic command listing & description
3. Advanced Description

On startup, slink2ew reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm SeedLink client module. In the control file, lines may begin with a valid slink2ew command (listed below) or with one of 2 special characters:

>     #  marks the line as a comment (example: # This is a comment).

>     @  allows control files to be nested; one control file can be
>        accessed from another with the command "@" followed by
>        a string representing the path name of the next control file
>        (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (commands are case sensative). Blank lines are also permitted in the control file.
The SeedLink protocol was originally developed at GEOFON as a component of the Seismological Communication Processor (SeisComP).

## 1. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by slink2ew, grouped by the function they influence. Most of the commands are required; they may be specified in any order in the control file.

            Earthworm system setup:
                    MyModuleId              required
                    RingName                required
                    HeartBeatInterval       required
                    Verbosity		optional

            SeedLink server and connection parameters:
                    SLaddr                  required
                    SLport                  required
    		Selectors		optional
    		Stream			optional
    		NetworkTimeout		optional
    		NetworkDelay		optional
    		KeepAlive		optional
    		MaxRate			optional
    		WriteMSEED		optional
    		SLRecSize		optional
    		instId			optional

    	Output control:
    		LogFile			required
    		StateFile		optional
    		StateFileInt		optional

## 2. ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description.

    command arg                                  processed by            in function

    MyModuleId mod_id                            ReadConfig              Earthworm setup

> Sets the module id for labeling all outgoing trigger, heartbeat, and error messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates to a unique single-byte number.

>     Default:  none
>     Example:  MyModuleId MOD_SLINK2EW_GE

    RingName ring                                ReadConfig              Earthworm setup

> Indicates which shared memory region to use for waveform output. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region.

>     Default:  none
>     Example:  RingName WAVE_RING

    HeartBeatInterval interval                   ReadConfig              Earthworm setup

> Defines the interval in seconds at which the module will issue TYPE_HEARTBEAT messages.

>     Default:  none
>     Example:  HeartBeatInterval 30

    Verbosity  level                             ReadConfig              Earthworm setup

> Specifies the level of logging verbosity. Level 0 is rather quiet and mostly reports errors, level 1 shows negotiation details and every received packet and level 2 shows a lot of details.

>     Default:  0
>     Example:  Verbosity 0

    SLaddr address                               ReadConfig              SeedLink parameters

> Specify the address of the SeedLink server. This can be either on IP address (four period-separated numbers) or the domain name of the server.

>     Default:  none
>     Example:  SLaddr      rtserve.iris.washington.edu

    SLport port                                  ReadConfig              SeedLink parameters

> Specifies the IP port number for the SeedLink server. This is commonly 18000.

>     Default:  none
>     Example:  SLport  18000

    Selectors selectors                          ReadConfig              Data selection

> Specify the SeedLink selectors for uni-station mode or default selectors for multi-station mode. Multiple selectors must be enclosed by quotes. If Stream commands are also specified in the command file, implying multi-station mode, any selectors specified with this command will be used as defaults when no data stream selectors are specified with a given Stream command.

>     Default:  none
>     Example:  Selectors  "BH?.D LH?.D"

    Stream streamkey [selectors]                 ReadConfig              Data selection

> Specifies one stream of data to be requested from the remote SeedLink server. This command implies the use of multi-station mode and can be specified multiple times to requested multiple data streams. The streamkey is composed of a network and station code separated by an underscore. Optional SeedLink selectors may be specified after the stream key. Multiple selectors must be enclosed in quotes. Beware of collecting multiple data streams with the same station code and differing location codes as the rest of Earthworm does not know about location codes, so the two data streams would get mixed together with bad results.

>     Default:  none
>     Example:  Stream  GE_DSB  "BH?.D HH?.D"

    NetworkTimeout timeout                       ReadConfig              Earthworm setup

> Sets the network timeout in seconds. If the module has not received any packets from the remote SeedLink server in this amount of time the connection will be closed and re-opened if possible. A value of 0 disables this feature.

>     Default:  600
>     Example:  NetworkTimeout 300

    NetworkDelay delay                           ReadConfig              Earthworm setup

> Sets the re-connection delay in seconds. After the connection to the remote SeedLink server has been broken (network timeout or any other connection problems) the module will wait this many seconds before attempting to re-connect.

>     Default:  30
>     Example:  NetworkDelay 10

    KeepAlive interval                           ReadConfig              Data Selection

> Specifies the interval in seconds that the module will send keep alive (heartbeat) packets to the remote SeedLink server. A value of 0 disables the feature. This feature only works with versions of SeedLink 2.93 or greater. This is useful for keeping a network connection open that might be closed by itermediate firewalls/gateways when the data stream only flows at intervals.

>     Default:  0 (disabled)
>     Example:  KeepAlive   600

    MaxRate rate                                 ReadConfig              Earthworm setup

> Specifies the maximum rate in bytes per second that the module will receive data and generate TraceBuf packets. A value of 0 disables the feature. This is useful for limiting the rate that TraceBuf packets are forwarded to the local system. In particular, during times of backfill data may be delivered by the upstream server faster than the local system can process the packets.

>     Default:  0  (disabled, no rate limit)
>     Example:  MaxRate   204800   (i.e. 200 kilobytes/second)

    WriteMSEED switch                            ReadConfig              Earthworm setup

> Sets the switch to control whether MSEED message types will be sent to the transport ring. By default, the module will create TRACEBUF2 messages.

>     Default:  0 (disabled)
>     Example:  WriteMSEED 1

    SLRecSize bytes                              ReadConfig              Earthworm setup

> Sets the miniSEED record size in bytes expected from the SeedLink server. The standard record length for SeedLink is 512-bytes. In specialized cases SeedLink servers can be configured to transmit other record sizes such as 256 or 128 bytes (usually to reduce the data latency), slink2ew must be configured to match the record length expected.

>     Default:  512
>     Example:  SLRecSize 256

    instId ID                                    ReadConfig              Earthworm setup

> Override the installation ID included in TraceBuf packets. By default the installation ID is that of the local system as defined by the EW_INSTALLATION environment variable. This option is useful for specifying the installation ID of the remote system providing the data or simply to avoid inserting the local ID.

>     Default:  (Local Installation ID)
>     Example:  instId   INST_UNKNOWN

    LogFile switch                               ReadConfig              Earthworm setup

> Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, coaxtoring will write a daily log file(s) called coaxtoringxx.log_yymmdd where xx is coaxtoring's module id (set with MyModuleId command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). If switch is 2 the log file is written but output to stdout and stderr is suppressed.

>     Default:  none
>     Example:  LogFile   1

    StateFile [filename]                         ReadConfig              Earthworm setup

> If this flag is specified a file with a list of sequence numbers is written, during a clean module shutdown, to the parameter directory with the name "slink<mod id>.state". Alternatively, a filename may be specified. During module startup these sequence numbers are used to resume data streams from the last received data. In this way continuous data can be collected even through system restarts. If this flag is not set the module will always request the next available data. Using this functionality is highly recommended unless you know that it is not necessary.

>     Default:  none
>     Example:  StateFile

    StateFileInt interval                        ReadConfig              Earthworm setup

> This option specifies the interval for saving the state file in number of packets received. In otherwords, using the default interval of 100, the statefile will be updated every 100 packets received. The purpose of this functionality is to minimize the amount of duplicate data collected if the module is ever killed without saving the current state information.

>     Default:  100
>     Example:  StateFileInt 500

## 3. Advanced Description

    SeedLink data transfer, all/uni-station and multi-station mode

> The SeedLink protocol allows two different modes of data transfer. All or uni-station mode is the method used for transmitting all stations from a node. In this case the client does not specify a stream key (network and station code) as the data stream is implied to be whatever is available from the server. Multi-station mode is the method used for requesting multiple, selected data streams (stations).
> For slink2ew the presence of one or more Stream commands in the configuration file triggers multi-station mode. Otherwise the module defaults to all/uni-station mode.

    SeedLink selectors

> SeedLink selectors are used to request specific types of data within a given data stream, in effect limiting the default action of sending all data types. A data packet is sent to the client if it matches any positive selector (without leading "!") and doesn't match any negative selectors (with a leading "!"). The general format of selectors is LLSSS.T, where LL is location, SSS is channel and T is type (one of [DECOTL] for Data, Event, Calibration, Blockette, Timing, and Log records). "LL", ".T", and "LLSSS." can be omitted, implying anything in that field. It is also possible to use "?" in place of L and S as a single character wildcard. Multiple selectors are separated by space(s).
> Some examples:

>     BH?          - BHZ, BHN, BHE (all record types)
>     00BH?.D      - BHZ, BHN, BHE with location code '00' (data records)
>     BH? !E       - BHZ, BHN, BHE (excluding detection records)
>     BH? E        - BHZ, BHN, BHE & detection records of all channels
>     !LCQ !LEP    - exclude LCQ and LEP channels
>     !L !T        - exclude log and timing records

> For slink2ew only data records will be written to the ring. In other words, requesting any records in addition to data records is a waste and you should always append ".D" to any specified selectors.

    SeedLink selector examples

>     #Selecting a two specific stations and a sub-set of their channels
>     Stream  GE_DSB   "BH?.D HH?.D"
>     Stream  II_KONO  00BH?.D

>     # Wildcards can be used with servers that support them, get all TA network stations
>     Stream  TA_*

Module Index | slink2ew Overview

Contact: chad at iris.washington.edu