Changes between Version 2 and Version 3 of slink2ew


Ignore:
Timestamp:
03/18/12 18:34:35 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • slink2ew

    v2 v3  
    2222SeisComP and !SeedLink are actively supported by the [http://www.gfz-potsdam.de/geofon/ GEOFON Project], [http://orfeus.knmi.nl/ ORFEUS Data Center] and [http://www.iris.edu/ IRIS Data Management Center] in addition to the user community. 
    2323 
     24 
     25On 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 (SeedLink is a component of the Seismological Communication Processor, or SeisComP, originally developed  at GEOFON). In the control file, lines may begin with a valid slink2ew command (listed below) or with one of 2 special characters: 
     26{{{ 
     27#  marks the line as a comment (example: # This is a comment). 
     28    
     29@  allows control files to be nested; one control file can be  
     30   accessed from another with the command "@" followed by  
     31   a string representing the path name of the next control file  
     32   (example: @model.d). 
     33}}} 
     34Command 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. 
     35 
     36=== FUNCTIONAL COMMAND LISTING === 
     37 
     38Below 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. 
     39{{{ 
     40        Earthworm system setup: 
     41                MyModuleId              required 
     42                RingName                required 
     43                HeartBeatInterval       required 
     44                Verbosity               optional 
     45 
     46        SeedLink server and connection parameters: 
     47                SLaddr                  required 
     48                SLport                  required 
     49                Selectors               optional 
     50                Stream                  optional 
     51                NetworkTimeout          optional 
     52                NetworkDelay            optional 
     53                KeepAlive               optional 
     54                ForceTraceBuf1          optional  (slink2ew >= 1.1) 
     55 
     56        Output control: 
     57                LogFile                 required 
     58                StateFile               optional 
     59                StateFileInt            optional 
     60}}} 
     61 
     62=== ALPHABETIC COMMAND LISTING & DESCRIPTION === 
     63 
     64In 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. 
     65 
     66The following list is organized by: 
     67 
     68command [argument here] 
     69 
     70 
     71'''!ForceTraceBuf1 [switch]'''[[BR]] 
     72Processed by: !ReadConfig[[BR]] 
     73Function: Earthworm setup 
     74            
     75Sets the on-off switch to force the creation of TRACEBUF messages on systems that support TRACEBUF2 messages. By default, the module will create TRACEBUF2 messages on systems that support them otherwise it will create the older TRACEBUF messages. This switch has no effect on systems that do no support TRACEBUF2 messages. This switch could be useful in environments where a transition is occuring between TRACEBUF and TRACEBUF2 messages, otherwise most people will never use this. 
     76{{{ 
     77Default:  0 (disabled) 
     78Example:  ForceTraceBuf1 1 
     79}}} 
     80 
     81'''!HeartBeatInterval [interval]'''[[BR]] 
     82Processed by: !ReadConfig[[BR]] 
     83Function: Earthworm setup 
     84            
     85Defines the interval in seconds at which the module will issue TYPE_HEARTBEAT messages. 
     86{{{ 
     87Default:  none 
     88Example:  HeartBeatInterval 30 
     89}}} 
     90 
     91'''!LogFile [switch]'''[[BR]] 
     92Processed by: !ReadConfig[[BR]] 
     93Function: Earthworm setup 
     94            
     95Sets 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. 
     96{{{ 
     97Default:  none 
     98Example:  LogFile   1 
     99}}} 
     100   
     101'''!KeepAlive [interval]'''[[BR]] 
     102Processed by: !ReadConfig[[BR]] 
     103Function: Data Selection 
     104            
     105Specifies 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. 
     106{{{ 
     107Default:  0 (disabled) 
     108Example:  KeepAlive   600 
     109}}} 
     110 
     111'''!MyModuleId [mod_id]'''[[BR]] 
     112Processed by: !ReadConfig[[BR]] 
     113Function: Earthworm setup 
     114 
     115Sets 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. 
     116{{{ 
     117Default:  none 
     118Example:  MyModuleId MOD_SLINK2EW_GE 
     119}}} 
     120 
     121'''!NetworkDelay [delay]'''[[BR]] 
     122Processed by: !ReadConfig[[BR]] 
     123Function: Earthworm setup 
     124 
     125Sets 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. 
     126{{{ 
     127Default:  30 
     128Example:  NetworkDelay 10 
     129}}} 
     130 
     131'''!NetworkTimeout [timeout]'''[[BR]] 
     132Processed by: !ReadConfig[[BR]] 
     133Function: Earthworm setup 
     134 
     135Sets 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. 
     136{{{ 
     137Default:  600 
     138Example:  NetworkTimeout 300 
     139}}} 
     140 
     141'''!RingName [ring]'''[[BR]] 
     142Processed by: !ReadConfig[[BR]] 
     143Function: Earthworm setup 
     144            
     145Indicates 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. 
     146{{{ 
     147Default:  none 
     148Example:  RingName WAVE_RING 
     149}}} 
     150 
     151'''Selectors [selectors]'''[[BR]] 
     152Processed by: !ReadConfig[[BR]] 
     153Function: Data selection 
     154            
     155Specify 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. 
     156{{{ 
     157Default:  none 
     158Example:  Selectors  "BH?.D LH?.D" 
     159}}} 
     160 
     161'''SLaddr [address]'''[[BR]] 
     162Processed by: !ReadConfig[[BR]] 
     163Function: !SeedLink parameters 
     164            
     165Specify the address of the !SeedLink server. This can be either on IP address (four period-separated numbers) or the domain name of the server. 
     166{{{ 
     167Default:  none 
     168Example:  SLaddr      st27.gfz-postdam.de 
     169}}} 
     170 
     171'''SLport [port]'''[[BR]] 
     172Processed by: !ReadConfig[[BR]] 
     173Function: !SeedLink parameters 
     174            
     175Specifies the IP port number for the !SeedLink server.  This is commonly 18000. 
     176{{{ 
     177Default:  none 
     178Example:  SLport  18000 
     179}}} 
     180 
     181'''!StateFile'''[[BR]] 
     182Processed by: !ReadConfig[[BR]] 
     183Function: Earthworm setup 
     184            
     185If 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".  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. 
     186{{{ 
     187Default:  none 
     188Example:  StateFile 
     189}}} 
     190 
     191'''!StateFileInt [interval]'''[[BR]] 
     192Processed by: !ReadConfig[[BR]] 
     193Function: Earthworm setup 
     194 
     195This 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. 
     196{{{ 
     197Default:  100 
     198Example:  StateFileInt 500 
     199}}} 
     200 
     201'''Stream streamkey [selectors]'''[[BR]] 
     202Processed by: !ReadConfig[[BR]] 
     203Function: Data selection  
     204            
     205Specifies 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. 
     206{{{ 
     207Default:  none 
     208Example:  Stream  GE_DSB  "BH?.D HH?.D" 
     209}}} 
     210 
     211'''Verbosity [level]'''[[BR]] 
     212Processed by: !ReadConfig[[BR]] 
     213Function: Earthworm setup  
     214            
     215Specifies 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. 
     216{{{ 
     217Default:  0 
     218Example:  Verbosity 0 
     219}}} 
     220 
     221=== Advanced Description === 
     222==== SeedLink data transfer, uni-station and multi-station mode ==== 
     223The SeedLink protocol allows two different modes of data transfer.  Uni-station mode is the method used for transmitting a single data stream (station) over a single network connection.  In this case the client does not specify a stream key (network and station code) as the data stream is implied by which address and port the client connects to (similar to LISS Protocol ver.  1).  Multi-station mode is the method used for transmitting multiple data streams (stations) multiplexed together over a single network connection.  Uni-station mode is supported by all current SeedLink versions.  Multi-station mode is supported by SeedLink 2.5 or later (SeisComP-1.1.6 or later). 
     224 
     225For slink2ew the presence of one or more Stream commands in the configuration file triggers multi-station mode.  Otherwise the module defaults to uni-station mode. 
     226 
     227==== SeedLink selectors ==== 
     228SeedLink 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). 
     229 
     230Some examples: 
     231{{{ 
     232BH?          - BHZ, BHN, BHE (all record types) 
     23300BH?.D      - BHZ, BHN, BHE with location code '00' (data records) 
     234BH? !E       - BHZ, BHN, BHE (excluding detection records) 
     235BH? E        - BHZ, BHN, BHE & detection records of all channels 
     236!LCQ !LEP    - exclude LCQ and LEP channels 
     237!L !T        - exclude log and timing records 
     238}}} 
     239For 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. 
     240 
     241=== Sample Configuration File === 
     242{{{ 
     243# 
     244#                     Configuration File for slink2ew 
     245# 
     246MyModuleId       MOD_SLINK2EW 
     247RingName         WAVE_RING       # Transport ring to write output to. 
     248  
     249HeartBeatInterval     30         # Heartbeat interval, in seconds. 
     250LogFile               1          # 1 -> Keep log, 0 -> no log file 
     251                                 # 2 -> write to module log but not stderr/stdout 
     252#Verbosity      0                # Set level of verbosity. 
     253 
     254SLhost     st27.gfz-potsdam.de   # Host address of the SeedLink server 
     255SLport         18000             # Port number of the SeedLink server 
     256 
     257StateFile      slink2ew.GE       # File with a list of sequence numbers which 
     258                                 # is read during module startup to resume 
     259                                 # data streams.  This file is written on a 
     260                                 # clean module shutdown.  If this is not 
     261                                 # specified as an absolute path the value of 
     262                                 # the environment variable EW_PARAMS will 
     263                                 # be pre-pended to this value.  Using this 
     264                                 # functionality is highly recommended. 
     265 
     266#NetworkTimeout 600              # Network timeout, after this many idle 
     267                                 # seconds the connection will be reset. 
     268                                 # Default is 600 seconds, 0 to disable. 
     269 
     270#NetworkDelay   30               # Network re-connect delay in seconds. 
     271 
     272#KeepAlive      0                # Send keepalive packets (when idle) at this 
     273                                 # interval in seconds.  Default is 0 (disabled). 
     274 
     275#ForceTraceBuf1 0                # On systems that support TRACEBUF2 
     276                                 # messages this flag will force the module 
     277                                 # to create TRACEBUF messages instead. 
     278                                 # Most people will never need this. 
     279 
     280# Selectors and Stream's.  If any Stream lines are specified the connection 
     281# to the SeedLink server will be configured in multi-station mode using 
     282# Selectors, if any, as defaults.  If no Stream lines are specified the 
     283# connection will be configured in uni-station mode using Selectors, if any. 
     284 
     285Selectors      "BH?.D"           # SeedLink selectors.  These selectors are used 
     286                                 # for a uni-station mode connection.  If one 
     287                                 # or more 'Stream' entries are given these are 
     288                                 # used as default selectors for multi-station 
     289                                 # mode data streams.  See description of 
     290                                 # SeedLink selectors below.  Multiple selectors 
     291                                 # must be enclosed in quotes. 
     292 
     293 
     294# List each data stream (a network and station code pair) that you 
     295# wish to request from the server with a "Stream" command.  If one or 
     296# more Stream commands are given the connection will be configured in 
     297# multi-station mode (multiple station data streams over a single 
     298# network connection).  If no Stream commands are specified the 
     299# connection will be configured in uni-station mode, optionally using 
     300# any specified "Selectors".  A Stream command should be followed by a 
     301# stream key, a network code followed by a station code separated by 
     302# an underscore (i.e. IU_KONO).  SeedLink selectors for a specific 
     303# stream may optionally be specified after the stream key.  Multiple 
     304# selectors must be enclosed in quotes.  Any selectors specified with 
     305# the Selectors command above are used as defaults when no selectors 
     306# are specified for a given stream. 
     307 
     308# Combined with the above specified default selectors the BHx channels 
     309# will be requested for each of these stations except for DSB for which 
     310# we also want the LHx channels. 
     311 
     312Stream  GE_DSB   "BH?.D LH?.D" 
     313Stream  GE_ISP 
     314Stream  GE_APE 
     315Stream  GE_STU 
     316}}} 
     317 
    24318== Helpful Hints ==