Earthworm Module: gcf2ew
Contributed by:
Function
Guralp Digitizers Earthworm feed via direct connection to serial port or TCP terminal server. (Solaris and Linux only) (new in EW v7.0) (Linux capable in v7.3)
Details
gcf2ew is a Guralp Digitizer GCF DM data feeding program for Earthworm. The gcf2ew module provides for three modes of data input:
- Lantronix MSS100 serial to IP server
- Direct Serial connection to a DM
- Network connection to gcfserv
This version uses a Lantronix MSS100 for the reliable transmission of data over a network. It also provides the capability for direct serial connection to a DM24 digitizer from a Solaris workstation. The direct serial connection makes full use of the BRP protocol that DM24's use to correct for serial line errors. In addtion, the gcfserv program can be used to serve data to multiple receivers using a PULL protocol that the gcf2ew module is configured for. V1.0.0 and later has SCNL capability for EW v7.0 and greater. It needs to be compiled with EW v7.0 and later, but is backward compatible to earlier versions of Earthworm. When running with an MSS100 or gcfserv, the module provides a reliable reconnection if the IP connection should drop. The network input also uses the Guralp BRP serial protocol to rewind the DM to request missing packets.
Configuration File Commands
On startup, gcf2ew reads the configuration file named on the command line. As always, the configuraton file contains comments:
# marks the line as a comment (example: # This is a comment).
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). gcf2ew supports one diagnostic command line option, -v is for verbose mode so that you can see packets coming in.
EXAMPLE CONFIGURATION FILE
# # gcf2ew configuration file # # This code receives GCF packets from an MSS100, converts them into # Earthworm trace buf messages, and stuffs them into a wave ring. # # ModuleId MOD_GCF2EW # module id for this import, RingName WAVE_RING # transport ring to use for input/output, HeartbeatInt 10 # Heartbeat interval in seconds # this should be half the g2ew.desc heartbeat! LogFile 1 # If 0, don't write logfile at all, SaveSOH2LOG 1 # write LOG chans to log file # this is useful for debugging timing or # data logger problems. TimeoutNoSend 5 # If no data for X seconds from GCF for # X seconds, then kill process (HB and # main thread). # NOTE: this timeout does not take effect until # a trace data packet comes from the MSS100. That # is, LOG channels do not count! # # Iff TimeoutNoSend == 0, then this data # check is DISABLED and gcf2ew will only die # if EW dies. # # one of the following input modes should be used # HostAddress mss # the IP or hostname of the MSS100 unit PortNumber 3001 # the port number of the MSS100 unit # OR #gcfservAddress isti # the IP or hostname of the gcfserv program #PortNumber 45670 # the port number of the gcfserv program # OR #SerialPort /dev/term/a # the serial port to which the DM is connected #BaudRate 19200a # an allowed baud rate for the solaris serial ports # The following mapping is used to map a system_id and stream_id to an SCN and as # a SELECTOR on those channels which should be passed along to Earthworm...channels not # matching the criteria below are dumped. # Example # Sys Strm S C N InfoSCN 0D0081 1031Z2 ISTI HHZ CI InfoSCN 0D0081 1031N2 ISTI HHN CI InfoSCN 0D0081 1031E2 ISTI HHE CI
FUNCTIONAL COMMAND LISTING
Below are the configure commands recognized by gcf2ew, grouped by the function they influence. Most of the commands are required.
Earthworm system setup: MyModuleId required RingName required HeartbeatInt required TimeoutNoSend required Input Control: HostAddress required PortNumber required or gcfservAddress required PortNumber required or SerialPort required BaudRate required Output Control: LogFile required SaveSOH2LOG optional InfoSCN required InfoSCNL 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]
HeartbeatInt [beat]
Processed By: HeartBeat
Function: Earthworm setup
Beat the gcf2ew heart every beat seconds. This is implemented as a separate thread in gcf2ew.
HostAddress [IPname or number]
Processed by: main
Function: Earthworm setup
Connect to the mss100 at the ip address IP address. This option accepts fully qualified domain names as well as IP numbers. Note that the PortNumber is also required.
gcfservAddress [IPname or number]
Processed by: main
Function: Earthworm setup
Connect to the gcfserv module at the ip address IP address. This option accepts fully qualified domain names as well as IP numbers. Note that the PortNumber is also required. Default port numbers for gcfserv are 45670.
SerialPort [SerialDevice]
Processed by: main
Function: Earthworm setup
Connect to the DM24 at the SerialDevice specified. To use this input mode, a BaudRate must also be provided.
BaudRate [rate]
Processed by: main
Function:Earthworm setup
Connect to the DM24 at the BaudRate rate specified. To use this input mode, the SerialPort directive must also be used. The baud rates are the standard allowable rates on a solaris host: 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200.
SaveSOH2LOG [switch]
Processed by: none
Function: Main gcf2ew Thread
Sets the on-off switch for writing GSL GCF STATUS channels to the LogFile. If switch is 0, no LOG channels will be written to the log. If switch is 1, gcf2ew will write all LOG channels to the LogFile. Turning this on will automatically turn on writing of a LogFile.
Default: 0 - do not use logit() for LOG channels
LogFile [switch]
Processed by: GetConfig
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 1, gcf2ew will write a daily log file(s) called gcf2ewxx.log_yymmdd where xx is gcf2ew'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).
Default: none
MyModuleId [mod_id]
Processed by: GetConfig
Function: Earthworm setup
Sets 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.
Default: none Calnet: MyModuleId MOD_Q2EW
RingName [ring]
Processed by: GetConfig
Function: Earthworm setup
This is the ring into which the waveforms and messages are sent.
Default: none, required option ATWC: RingName WAVE_RING
InfoSCN [System Stream S C N]
Processed by: insertSCN
Function: Main gcf2ew Thread
This command is used to define how gcf2ew maps a System and Stream ID to a Station Channel Name. It is also used as a channel selector as only those streams specified get passed on to the Earthworm Wave Ring. System is for the DM System ID name, Stream is for the DM Stream ID name ...aka channel name in GCF, S is for station name, C is for channel identifier, and N is for network code.
# Sys Strm S C N InfoSCN 0D0081 1031Z2 ISTI HHZ CI InfoSCN 0D0081 1031N2 ISTI HHN CI InfoSCN 0D0081 1031E2 ISTI HHE CI
InfoSCNL [System Stream S C N L]
Processed by: insertSCN
Function: Main gcf2ew Thread
This command is used to define how gcf2ew maps a System and Stream ID to a Station Channel Name. It is also used as a channel selector as only those streams specified get passed on to the Earthworm Wave Ring. This forces the trace buf type to be of type TRACEBUF2. InfoSCN and InfoSCNL cannot be mixed. System is for the DM System ID name, Stream is for the DM Stream ID name ...aka channel name in GCF, S is for station name (5 chars), C is for channel identifier (3 chars), N is for network code (2 chars), and L is for location code (2 chars).
# Sys Strm S C N L InfoSCNL 0D0081 1031Z2 ISTI HHZ CI 00 InfoSCNL 0D0081 1031N2 ISTI HHN CI 00 InfoSCNL 0D0081 1031E2 ISTI HHE CI 00
PortNumber [number]
Processed by: main
Function: Earthworm setup
Connect to the mss100 or gcfserv at the ip address specified and this port number. Note that the HostAddress or gcfservAddress is also required for this directive. PortNumber defaults to 3001 for mss and 45670 for gcfserv.
TimeoutNoSend [timeout]
Processed by: HeartBeat
Function: Earthworm setup
If no waveform packets come from the DM after timeout seconds, the gcf2ew module will notify statmgr and die. If timeout is set to 0, then the gcf2ew module will never check for this timeout. If set to 0, gcf2ew will only die if the Earthworm system calls for its termination. This timeout begins once the first Waveform packet is received from the DM served by this MSS100.
Default: none, required option ATWC: TimeoutNoSend 0
DESCRIPTOR FILE EXAMPLE
Here is a copy of the gcf2ew.desc file as implemented. Note that all causes of death for gcf2ew feed through the function gcf2ew_die() which logs all causes of death using logit() and sends a message to the statmgr utility.
modName gcf2ew modId MOD_GCF2EW instId INST_UNKNOWN restartMe # restart this sucker as it is critical to data collection # # # Heartbeat Specification. If the status manager does not receive # a heartbeat message every seconds from this module, an # error will be reported (client module dead). is the maximum # number of pager messages that will be reported and is the # maximum number of email messages that will be reported. If the # page or mail limit is exceeded, no further errors will be reported # until the status manager is restarted. # tsec: 30 page: 0 mail: 99 # from die.h: #define GCF2EW_DEATH_SIG_TRAP 1 #define GCF2EW_DEATH_EW_PUTMSG 2 #define GCF2EW_DEATH_EW_TERM 3 #define GCF2EW_DEATH_EW_CONFIG 4 #define GCF2EW_DEATH_GCF_TIMEOUT 5 # these are the statmgr messages that gcf2ew will send before dieing # err: 1 nerr: 1 tsec: 0 page: 5 mail: 20 text: "SIGNAL caused gcf2ew to die" # err: 2 nerr: 1 tsec: 0 page: 5 mail: 20 text: "EW tport_putmsg() failed, gcf2ew dead" # err: 3 nerr: 1 tsec: 0 page: 5 mail: 20 text: "EW TERMINATE recv'd, gcf2ew dead" # err: 4 nerr: 1 tsec: 0 page: 5 mail: 20 text: "EW config problems on startup, gcf2ew dead" # err: 5 nerr: 1 tsec: 0 page: 5 mail: 20 text: "gcf2ew received NO DATA for configured TIMEOUT and died" #