Changes between Initial Version and Version 1 of ew2liss

03/02/12 07:45:50 (10 years ago)



  • ew2liss

    v1 v1  
     3= [wiki:Earthworm Earthworm] Module: ew2liss = 
     4'''Contributed by: ''' 
     6== Function == 
     7Ew2liss is the Earthworm module for serving Earthworm trace data in LISS (Live Internet Seismic Server) format. 
     9== Details == 
     11Ew2liss is the Earthworm module for serving Earthworm trace data in LISS (Live Internet Seismic Server: format. The LISS is a very simple service that provides trace data in miniSEED format in near-real-time over the Internet. The ew2liss module will convert selected SCNs (station-component-network) of trace data from an Earthworm transport ring, convert that data to miniSEED format, and serve the data to a single LISS client (such as [wiki:liss2ew liss2ew]) over a TCP/IP network connection. 
     13One 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. Note that nothing prevents ew2liss from handling SCNs from many stations except this LISS convention. It may be that ew2liss and liss2ew could be used to exchange data between Earthworm installations. Since LISS uses Steim-2 compression, this format should use less network bandwidth than Earthworm's export_scn/import pair. Performing the compression and decompression will use more CPU time, however. 
     15'''A comment about timing'''  
     17Earthworm trace data (TRACE_BUF format) includes "starttime" and "endtime" (8-byte floating-point numbers) to mark the start and end times of each message. It also includes sample count (an integer) and samplerate (an 8-byte floating-point number). Frequently this samplerate value has been set to the '''nominal''' sample rate; the start and end times are assumed to be actual measured values. 
     19The miniSEED format includes only a start time for each record. The sample rate is encoded in the data fixed record as two two-byte integers. These two integers are treated as multipliers if positive, divisors if negative; this a wide range of sample rate values can be expressed. In converting from Earthworm TRACE_BUF messages to miniSEED, errors would be introduced if the nominal sample rate was used to set the miniSEED sample rate factors. Instead, a '''best''' rate is determined from the starttime, endtime, and sample count values. Then this new sample rate is rounded to the nearest 0.0001 samples per second. This rounded is intended to reduce the discretization introduced by the conversion to the short integer rate factors. Finally, this new sample rate is used to set the miniSEED sample rate factors. 
     23On startup, ew2liss reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm LISS server module. (LISS is the Live Internet Seismic Server.) In the control file, lines may begin with a valid ew2liss command (listed below) or with one of 2 special characters: 
     26#  marks the line as a comment (example: # This is a comment). 
     28@  allows control files to be nested; one control file can be 
     29   accessed from another with the command "@" followed by 
     30   a string representing the path name of the next control file 
     31   (example: @model.d). 
     33Command 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. 
     37Below are the commands recognized by ew2liss, grouped by the function they influence. Most of the commands are required; they may be specified in any order in the control file. 
     40   Earthworm system setup: 
     41                MyModuleId            required 
     42                InRing                 required 
     43                HeartBeatInterval      required 
     44                GetWavesFrom       required 
     45                Debug              optional 
     47        LISS server parameters: 
     48                LISSaddr                required 
     49                LISSport                required 
     50                SeqFile          required 
     51                SocketTimeout           optional 
     53        Data input parameters: 
     54                MaxSCNs                 required 
     55                ServeSCN              required 
     60In 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. 
     62The following list is organized by: 
     64command [argument here] 
     67Processed by: ReadConfig[[BR]] 
     68Function: Earthworm setup 
     70Turns on debug logging for ew2liss. Currently does nothing at all. 
     72Default:  no debug logging 
     73Example:  Debug 
     76'''!GetWavesFrom [inst mod_id]'''[[BR]] 
     77Function: Earthworm setup 
     79Controls the TRACE_BUF messages input to ew2liss. Ew2liss will only process TRACE_BUF messages that come from module mod_id at installation inst. inst and mod_id are character strings (valid strings are listed in earthworm.d) which are related to single-byte numbers that uniquely identify each installation and module. Only 1 "GetWavesFrom" command may be issued; wildcards (INST_WILDCARD and MOD_WILDCARD) will force ew2liss to process all TRACE_BUF messages, regardless of their place of origin. 
     81Default:  none 
     82Example:   GetWavesFrom  INST_MENLO  MOD_WILDCARD 
     85'''!HeartBeatInterval [nsec]'''[[BR]] 
     86Processed by: ReadConfig[[BR]] 
     87Function: Earthworm Setup 
     89Defines the number of seconds, nsec between TYPE_HEARTBEAT messages issued by ew2liss. 
     91Default:  none 
     92Example:  HeartBeatInterval 30 
     95'''!InRing [ring]'''[[BR]] 
     96Processed by: ReadConfig[[BR]] 
     97Function: Earthworm setup 
     99Tells ew2liss which shared memory region to use for input. 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. 
     101Default:  none 
     102Example:  InRing WAVE_RING 
     105'''LISSaddr [address]'''[[BR]] 
     106Processed by: ReadConfig[[BR]] 
     107Function: LISS parameters 
     109Specify the address of the nework interface on the earthworm computer that you want to use for serving LISS. This can be either on IP address (four period-separated numbers) or the domain name of the server. 
     111Default:  none 
     112Example:  LISSaddr 
     115'''LISSport [port]'''[[BR]] 
     116Processed by: ReadConfig[[BR]] 
     117Function: LISS parameters 
     119Specifies the IP port number for the LISS. Normally this is 4000. But if you run more than one instance of ew2liss on one computer, they cannot use the same LISSaddr and LISSport. 
     121Default:  none 
     122Example:  LISSport  4000 
     125'''!LogFile [switch]'''[[BR]] 
     126Processed by: ReadConfig[[BR]] 
     127Function: Earthworm Setup 
     129Sets 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, ew2liss 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 ew2liss'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). 
     131Default:  none 
     132Example:  LogFile   1 
     135'''!MaxSCNs [n]'''[[BR]] 
     136Processed by: ReadConfig[[BR]] 
     137Function: Data Selection 
     139Specifies the number of ServeSCN commands to be found in this configuration file. 
     141Default:  none 
     142Example:  MaxSCNs   3 
     145'''!MyModuleId [mod_id]'''[[BR]] 
     146Processed by: ReadConfig[[BR]] 
     147Function: Earthworm setup 
     149Sets 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. 
     151Default:  none 
     152Example:  MyModuleId MOD_L2E_ANMO 
     155'''!SeqFile [filename]'''[[BR]] 
     156Processed by: ReadConfig[[BR]] 
     157Function: LISS Parameter 
     159Specifies the filename for the sequence number file, kept in the EW_PARAMS directory (environment variable). If this file does not exist, ew2liss will try to create it. From then on, it records the last sequence number used on a miniSEED record. These numbers are six digit decimal numbers. 
     161Default:  none 
     162Example:  SeqFile seq.lsn 
     165'''!ServeSCN [station component net location]'''[[BR]] 
     166Processed by: ReadConfig[[BR]] 
     167Function: Data selection 
     169Specifies one stream of data to be read from the transport ring and served as LISS 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). LISS channels may also identified by a location code. If you want, you can inlude a two-digit location code here; otherwise leave this blank. You must give one ServeSCN command for each SCN that you want to serve. 
     171Default:  none 
     172Example:  ServeSCN SEA BHZ UW 
     175'''!SocketTimeout [seconds]'''[[BR]] 
     176Processed by: ReadConfig[[BR]] 
     177Function: LISS parameters 
     179Defines 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. 
     181Default:  same as HeartBeatInterval 
     182Example:  SocketTimeout   20 
     185=== Sample Configuration File === 
     188#                     Configuration File for ew2liss 
     190MyModId          MOD_EW2LISS 
     191InRing          WAVE_RING        # Transport ring to read trace data from 
     192HeartBeatInterval     30         # Heartbeat interval, in seconds, 
     193LogFile               1          # 1 -> Keep log, 0 -> no log file 
     196# Specify logo of the messages to grab from the InRing. 
     197# TYPE_TRACEBUF is assumed, therefore only module ID and 
     198# installation ID need to be specified 
     200GetWavesFrom    INST_WILDCARD MOD_WILDCARD  # TYPE_TRACEBUF (assumed) 
     202LISSaddr           # IP address of the LISS (server) 
     203                                 # If you have DNS configured, you may also 
     204                                 # give the domain name of the LISS. 
     205LISSport    4000                 # Port number for LISS; often this is 4000 
     207SocketTimeout  30                # Socket timeout in seconds; not more than 
     208                                 # HeartBeatInterval 
     210SeqFile    seq.lsn               # Name of sequence number file. 
     211MaxSCNs        3                 # Number of SCNs to accept; must be at least 
     212                                 # the number of ServeSCN commands. 
     213# List each sta/comp/net that you want to serve with a 
     214# "ServeSCN" command. Location code (LC) is a 2-digit numerical code that 
     215# you may use to further identify the data stream. 
     216# Location code may be omitted (left blank); all other entries must be 
     217# given explicitly (no wildcards). 
     219#          site comp net LC 
     220#          ---- ---- --- -- 
     221ServeSCN  SEA   BHZ  UW 00 
     222ServeSCN  SEA   BHN  UW 00 
     223ServeSCN  SEA   BHE  UW 00 
     226== Helpful Hints ==