wiki:gcf2ew
Last modified 8 years ago Last modified on 05/02/12 09:38:40

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"
#

Helpful Hints