Changes between Version 2 and Version 3 of naqs2ew


Ignore:
Timestamp:
04/07/12 05:32:37 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • naqs2ew

    v2 v3  
    1616If naqs2ew experiences any socket errors or if !NaqsServer breaks the connection, naqs2ew closes the socket and issues a TYPE_ERROR message stating the reason the connection was dropped. It then goes back to looping on reconnection attempts. When the connection is reestablished, naqs2ew will issue another TYPE_ERROR message (really an "un-error" message), stating that everything's OK again. 
    1717 
     18== Configuration File Commands == 
     19On startup, naqs2ew reads the configuration file named on the command line. As always, the configuraton file contains comments: 
     20{{{ 
     21#  marks the line as a comment (example: # This is a comment). 
     22}}} 
     23Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). 
     24 
     25 
     26=== EXAMPLE CONFIGURATION FILE === 
     27{{{ 
     28# naqs2ew config file 
     29 
     30MyModuleId      MOD_NAQS2EW 
     31RingName        WAVE_RING 
     32HeartBeatInt    30 
     33 
     34LogFile         1 
     35Debug           0 
     36SocketDebug     0 
     37 
     38NaqsServer      192.168.1.1 28000   # IP address and Port of NaqsServer 
     39MaxSamplePerMsg 200 
     40 
     41TimeJumpTolerance 600  # (in seconds) This term is used to catch packets with 
     42                       # dubious timestamps.  If a time gap is detected in an 
     43                       # incoming data stream, the new packet's timestamp is 
     44                       # compared to the system clock.  If it is later than 
     45                       # the current system time by more than TimeJumpTolerance 
     46                       # seconds, naqs2ew assumes the packet timestamp is bogus 
     47                       # (it's in the future) and it ignores the entire packet. 
     48                       # NOTE: if you use this feature with small tolerances, 
     49                       # the PC's system clock must be kept pretty close to 
     50                       # network time!!! 
     51                       # Set to -1 if you never want to compare packet times 
     52                       # to the system clock. 
     53                       # Valid values are -1 or any number >= 0.0 
     54 
     55# Set up list of channels you want to receive from NaqsServer using 
     56# a 'RequestChannel' command for each channel, with these arguments: 
     57# 
     58#   sta       station code you want to receive data from (no wildcards). 
     59#   comp      component (channel) of data you want to receive (no wildcards). 
     60#   net       2-character network code to label this channel with (no wildcards). 
     61#             NaqsServer supplies its own station and component codes to its clients, 
     62#             but not a network code. The sta and comp codes you supply in this file 
     63#             must match the codes supplied by NaqsServer. The TYPE_TRACEBUF messages 
     64#             output to the Earthworm system will be labeled with the sta, comp, net 
     65#             codes listed in this file. 
     66# 
     67#   pinno     pin number to assign to this channel (0-32767) 
     68# 
     69#   delay     short-term-completion time (in seconds) -1s <= s <= 300s. 
     70#             When NaqsServer misses packets from the field, it will wait for the 
     71#             given amount of time for the gap to be filled by re-transmitted 
     72#             packets before sending data to naqs2ew. Specifying delay=0 will 
     73#             guarantee that packets are in chronological order, without 
     74#             waiting for missed data.  Setting delay=-1 will deliver the packets 
     75#             with no delay, in the order they were received (possibly out of 
     76#             chronological order). 
     77# 
     78#   format    format in which you want to receive the data: 
     79#              -1   = compressed packets (raw format from HRD) 
     80#               0   = uncompressed packets, original sample rate. 
     81#             0 < r = requested output sample rate.  NaqsServer will accomodate. 
     82# 
     83#   sendbuf   Buffer flag: 
     84#               0 = do not send buffered packets for these channels. 
     85#               1 = send buffered packets for these channels.  This effectively 
     86#                   moves the start of the data stream several packets into 
     87#                   the past. 
     88#             WARNING: if naqs2ew is auto-restarted with sendbuf = 1, 
     89#               duplicate data could enter the Earthworm system. 
     90#               Therefore, we strongly recommend setting sendbuf = 0. 
     91# 
     92#                 sta   comp  net  pinno  delay(s)   format  sendbuf 
     93RequestChannel    CSU    VDZ   NC   2001    30         0        0 
     94RequestChannel    CSU1   VDN   NC   2002    30         0        0 
     95RequestChannel    CSU1   VDE   NC   2003    30         0        0 
     96RequestChannel    CSU1   ADZ   NC   2004    30         0        0 
     97RequestChannel    CSU1   ADN   NC   2005    30         0        0 
     98RequestChannel    CSU1   ADE   NC   2006    30         0        0 
     99# 
     100}}} 
     101 
     102=== FUNCTIONAL COMMAND LISTING === 
     103Below are the configure commands recognized by naqs2ew, grouped by the function they influence. Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). Most of the commands are required. 
     104{{{ 
     105        Earthworm system setup: 
     106                MyModuleId              required 
     107                RingName                required 
     108                HeartbeatInt            required 
     109 
     110        Waveform acquistion: 
     111                NaqsServer              required 
     112                MaxSamplePerMsg         required 
     113                RequestChannel          required 
     114                TimeJumpTolerance   required 
     115 
     116        Output Control: 
     117                LogFile                 required 
     118                Debug                   optional 
     119                SocketDebug             optional 
     120}}} 
     121 
     122=== ALPHABETIC COMMAND LISTING & DESCRIPTION === 
     123In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), 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. 
     124 
     125The following list is organized by: 
     126 
     127command [argument here] 
     128 
     129'''Debug [flag]'''[[BR]] 
     130Function: Output Control 
     131 
     132Optional command to control the amount of logging done by naqs2ew. If flag is zero, debug-level logging is turned off; naqs2ew will do normal logging of start, stop, and error conditions. If flag is non-zero, naqs2ew will also make a line entry for every packet it sends and receives, and it will log the entire contents of every decompressed trace data packet. 
     133{{{ 
     134Default:  Debug 0 
     135}}} 
     136 
     137'''!HeartbeatInt [nsec]'''[[BR]] 
     138Function: Earthworm setup 
     139 
     140Defines the minimum number of seconds nsec between TYPE_HEARTBEAT messages issued by naqs2ew. The heartbeat is implemented within both the connection-making and the socket-reading loops of naqs2ew. 
     141{{{ 
     142Default:  none 
     143Example:  HeartbeatInt 30 
     144}}} 
     145 
     146'''!LogFile [switch]'''[[BR]] 
     147Function: Output Control 
     148 
     149Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written, but messages may go to stderr and/or stdout. If switch is 1, naqs2ew will write to stderr/stdout and to a daily log file(s) called naqs2ewxx.log_ccyymmdd where xx is naqs2ew's module id (set with "!MyModuleId" command) and ccyymmdd is the current UTC date (ex: 19960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). If switch is 2, the log file will be written, but no messages will go to stderr or stdout. 
     150{{{ 
     151Default:  none 
     152Example:  LogFile 1 
     153}}} 
     154 
     155'''!MaxSamplePerMsg [nsamp]'''[[BR]] 
     156Function: Waveform Acquisition 
     157 
     158Sets the maximum length of each outgoing TYPE_TRACEBUF message to nsamp samples. The number of samples in each TYPE_TRACEBUF message depends on the sample rate of the channel. Normally naqs2ew loads one-second's worth of data into each TYPE_TRACEBUF message. However, if the sample rate for a channel is greater than nsamp samples per second, naqs2ew limits that channel's TYPE_TRACEBUF messages to nsamp samples each. In processing a packet from NaqsServer, naqs2ew will buffer any fractional second of data until it receives the next packet for that channel in an attempt to always send out equal length messages. If naqs2ew detects a time tear between packets from NaqsServer, it may output a message containing less than one second of data. 
     159{{{ 
     160Default:  none 
     161Example:  MaxSamplePerMsg 200 
     162}}} 
     163 
     164'''!MyModuleId [mod_id]'''[[BR]] 
     165Function: Earthworm setup 
     166 
     167Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number. 
     168{{{ 
     169Default:  none 
     170Example:  MyModuleId MOD_NAQS2EW 
     171}}} 
     172 
     173'''!NaqsServer [IPaddress port]'''[[BR]] 
     174Function: Waveform Acquisition 
     175 
     176Identifies the IPaddress and port number of the !NaqsServer application to receive data from. 
     177{{{ 
     178Default:  none 
     179Example:  NaqsServer 192.168.1.1 28000 
     180}}} 
     181 
     182'''!RingName [ring]'''[[BR]] 
     183Function: Earthworm setup 
     184 
     185Tells naqs2ew 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. 
     186{{{ 
     187Default:  none 
     188Example:  RingName WAVE_RING 
     189}}} 
     190 
     191'''!RequestChannel [sta comp net pinno delay format sendbuf]'''[[BR]] 
     192Function: Waveform Acquisition 
     193 
     194Use one RequestChannel command for each channel of trace data that you want to request from !NaqsServer (no hard-coded limit). Details of the arguments are given below: 
     195{{{ 
     196  sta       station code you want to receive data from (up to 5 chars, no wildcards). 
     197 
     198  comp      component (channel) of data you want to receive (up to 3 chars, no wildcards). 
     199 
     200  net       network code to label this channel with (up to 2 chars,no wildcards). 
     201            NaqsServer supplies its own station and component codes to its clients, 
     202            but not a network code. The sta and comp codes you supply in this command 
     203            must match the codes supplied by NaqsServer. The TYPE_TRACEBUF messages 
     204            output to the Earthworm system will be labeled with the sta, comp, net 
     205            codes listed in this command. 
     206 
     207  pinno     pin number to assign to this channel (0-32767) 
     208 
     209  delay     short-term-completion time (in seconds) -1s <= s <= 300s. 
     210            When NaqsServer misses packets from the field, it will wait for the 
     211            given amount of time for the gap to be filled by re-transmitted 
     212            packets before sending data to naqs2ew. Specifying delay = 0 will 
     213            guarantee that packets are in chronological order, without 
     214            waiting for missed data.  Setting delay = -1 will deliver the packets 
     215            with no delay, in the order they were received (possibly out of 
     216            chronological order). 
     217 
     218  format    format in which you want to receive the data from NaqsServer: 
     219               -1   = compressed packets (raw format from HRD) 
     220                0   = uncompressed packets, original sample rate. 
     221              0 < r = requested output sample rate.  NaqsServer will accomodate. 
     222            Data is reformatted into Earthworm TYPE_TRACEBUF packets before it is 
     223            written to the transport ring. 
     224 
     225  sendbuf   Buffer flag: 
     226                0 = do not send buffered packets for these channels. 
     227                1 = send buffered packets for these channels.  This effectively 
     228                    moves the start of the data stream several packets into 
     229                    the past. 
     230            WARNING: if naqs2ew is auto-restarted with sendbuf = 1, 
     231              duplicate data could enter the Earthworm system (this is generally not 
     232              a good thing). Therefore, we strongly recommend setting sendbuf = 0. 
     233}}} 
     234{{{ 
     235Default:  none 
     236Example:  RequestChannel  CSU1 VDN NC 2002  30  0  0 
     237}}} 
     238 
     239'''!SocketDebug [flag]'''[[BR]] 
     240Function: Output Control 
     241 
     242Optional command to control the amount of logging done by the socket library. If flag is zero, debug-level logging is turned off. If flag is non-zero, the socket library write LOTS of debugging info. WARNING: turing socket debugging on generates huge log files. 
     243{{{ 
     244Default:  SocketDebug 0 
     245}}} 
     246 
     247'''!TimeJumpTolerance [flag]'''[[BR]] 
     248Function: Waveform Acquisition 
     249 
     250(in seconds) This term is used to catch packets with dubious timestamps. If a time gap is detected in an incoming data stream, the new packet's timestamp is compared to the system clock. If it is later than the current system time by more than !TimeJumpTolerance seconds, naqs2ew assumes the packet timestamp is bogus (it's in the future) and it ignores the entire packet. NOTE: if you use this feature with small tolerances, the PC's system clock must be kept pretty close to network time!!! Set to -1 if you never want to compare packet times to the system clock. Valid values are -1 or any number >= 0.0 
     251 
     252 
    18253== Helpful Hints ==