wiki:liss2ew

Version 4 (modified by branden, 9 years ago) (diff)

--

Earthworm Module: liss2ew

Contributed by:

Function

Liss2ew is the earthworm module for receiving trace data from the Live Internet Seismic Server.

Details

Liss2ew is the earthworm module for receiving trace data from the Live Internet Seismic Server. The LISS is a very simple service that provides trace data in miniSEED format in near-real-time over the Internet. The liss2ew module will connect to one LISS, read selected streams of trace data, and write that trace data into the earthworm transport ring. One LISS normally has data for a single station. One or more components are sent together in the data stream. In some cases, one component is provided in more than one sample-rate. The `location code' is used in this case to label the different kinds of data.

The miniSEED format may contain a few other types of blockettes besides the Data-Only blockette. Currently liss2ew ignores these non-trace-data blockettes.

Besides the ASL, there are several other LISS servers. Some digital seismographs produce miniSEED. There is be an earthworm LISS server module, ew2liss. This will allow the exchange of earthworm trace data by an alternate format to the current import/export combination.

On startup, liss2ew reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm LISS client module. (LISS is the Live Internet Seismic Server.) In the control file, lines may begin with a valid liss2ew 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 (upper/lower case matters!). Blank lines are also permitted in the control file.

FUNCTIONAL COMMAND LISTING

Below are the commands recognized by liss2ew, 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
                OutRing                 required
                HeartBeatInterval      required
                Debug

        LISS server and input parameters:
                LISSaddr                required
                LISSport                required
                lenSEED                 optional
                SocketTimeout           optional

        Data output parameters:
                TraceLength             required
                MaxSCNs                 required
                AcceptSCNL              required

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.

The following list is organized by:

command [argument here]

AcceptSCNL [station component net location pinno]
Processed by: ReadConfig
Function: Data selection

Specifies one stream of data to be read from the LISS and output as trace data. The station, component, and network are used to set the earthworm SCN of this data stream. These three parameters must be given explicitly (no wildcards). Many LISS channels are also identified by a location code. If you are getting data from the ASL LISS, see their table of available data streams. If you don't know the location code, you can try running dumpseed to see what is being served. The location code may be *, the wildcard. If you use the wildcard and more than one location code is available for this SCN, liss2ew will report errors such as samplerate changing as it reads first one location code and then the other. To enter the empty location code (seen on some ASL channels, use the empty string "". You must give one AcceptSCNL command for each SCN that you want to receive from the LISS. However, you should not specify more than one AcceptSCNL for the same SCN and different location codes. The rest of earthworm does not know about location codes, so the two data streams would get mixed together with bad results.

The pin number pinno is used for internal earthworm use.

Default:  none
Example:  AcceptSCNL ANMO BHZ IU 00   1234

Debug
Processed by: ReadConfig
Function: Earthworm setup

Turns on debug logging for liss2ew.

Default:  no debug logging
Example:  Debug

HeartBeatInterval [nsec]
Processed by: ReadConfig
Function: Earthworm Setup

Defines the number of seconds, nsec between TYPE_HEARTBEAT messages issued by liss2ew.

Default:  none
Example:  HeartBeatInterval 30

lenSEED [bytes]
Processed by: ReadConfig
Function: LISS parameters

Defines the number of bytes in the miniSEED records to be read from the LISS. For the ASL LISS, this is 512 bytes.

Default:  512
Example:  lenSEED 4096

LISSaddr [address]
Processed by: ReadConfig
Function: LISS parameters

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

Default:  none
Example:  LISSaddr      anmo.iu.liss.org

LISSport [port]
Processed by: ReadConfig
Function: LISS parameters

Specifies the IP port number for the LISS. Normally this is 4000.

Default:  none
Example:  LISSport  4000

LogFile [switch]
Processed by: ReadConfig
Function: 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 non-zero, liss2ew will write daily log file(s) called nnnnnxx.log_yyyymmdd where nnnnn is the name of the configuration file (with the suffix `.d' removed), xx is liss2ew's module id (set with MyModuleId? command) and yyyymmdd is the current UTC date (ex: 19960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).

Default:  none
Example:  LogFile   1

!MaxSCNs [n]
Processed by: ReadConfig
Function: Data Selection

Specifies the number of !AcceptSCNL commands to be found in this configuration file.

Default:  none
Example:  MaxSCNs   3

MyModuleId [mod_id]
Processed by: ReadConfig
Function: 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_L2E_ANMO

OutRing [ring]
Processed by: ReadConfig
Function: Earthworm setup

Tells liss2ew which shared memory region to use for 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:  OutRing WAVE_RING

SocketTimeout [seconds]
Processed by: ReadConfig
Function: LISS parameters

Defines the number of seconds to wait for response from the LISS. This time interval must not be large than the HeartBeatInterval. Unlike in certain other Earthworm modules, you cannot turn off the timeout by using a value of -1.

Default:  same as HeartBeatInterval
Example:  SocketTimeout   20

TraceLength [samples]
Processed by: ReadConfig
Function: Data parameters

Specify the number of samples to put in each TRACE_BUF message. Liss2ew always trace data in `long integer' (four byte) format. The total length of the output TRACE_BUF messages will be 64 + 4 * samples. Values are restricted to the range of 10 - 1000.

Default:  none
Example:  TraceLength  100

Sample Configuration File

#
#                     Configuration File for liss2ew
#
MyModId          MOD_LISS2EW
OutRing          WAVE_RING       # Transport ring to write output to,
HeartBeatInterval     30         # Heartbeat interval, in seconds,
LogFile               1          # 1 -> Keep log, 0 -> no log file
#Debug                           # Write out debug messages (optional)


LISSaddr   anmo.iu.liss.org      # IP address of the LISS (server)
                                 # If you have DNS configured, you may also
                                 # give the domain name of the LISS.
LISSport    4000                 # Port number for LISS; often this is 4000

lenSEED      512                 # The size of SEED records to read from LISS
                                 # OPTIONAL; defaults to 512 bytes.

SocketTimeout  30                # Socket timeout in seconds; not more than
                                 # HeartBeatInterval

TraceLength    100               # Number of trace data samples to put in one
                                 # TRACE_BUF packet. Range is 10 - 1000

MaxSCNs        3                 # Number of SCNs to accept; must be at least
                                 # the number of AcceptSCNL commands.
# List each sta/comp/net/location that you expect from LISS in an
# "AcceptSCNL" command. Location code (LC) is a 2-digit code to further
# identify a seismological data path. LC (and ONLY LC) may be given as `*' to
# specify a wildcard. If the LISS has more than one LC for a give SCN,
# using the wildcard will generate errors in log.
# Do NOT specify the same SCN with two different LC values, as this will
# cause great confusion within earthworm!!!!
# If liss2ew sees an SCNL which is not listed here, it will be ignored.
# On each line after the SCNL, list a pinnumber to use for this SCNL.

#          site comp net LC pinno
#          ---- ---- --- -- -----
AcceptSCNL  ANMO BHZ  IU 00 1234
AcceptSCNL  ANMO BH1  IU 00 1235
AcceptSCNL  ANMO BH2  IU 00 1236

Helpful Hints