Rockhound to Earthworm Data Relay

 

The Rock-to-EW module provides a data relay to the USGS Earthworm software package (http://folkworm.ceri.memphis.edu/ew-dist).   Rock-to-EW emulates an Earthworm "export_generic" module, providing a TCP/IP listen port for external "import" programs to connect to.

The data-output operation of this module is similar to "export_generic":  Messages are queued in a memory based FIFO, and sent to the receiving "import_generic", or similar program, via a TCP connection.  If the available bandwidth of the link is lower than the aggregate rate of messages being queued for shipping, the FIFO will eventually overflow.  In that case, an error is logged, and the queue becomes circular.  That is, if the queue is configured to be N messages long, it will contain the most recent N messages.  Two-way heartbeats are used to assure that the link is actually capable of transmitting data.  The heartbeats consist of agreed-upon text strings sent at an agreed-upon rate.  If a proper heartbeat is not received in time, it is presumed that the link is broken.  In this case, Rock-to-EW will log the error, close the connection, and then wait for the import program to reestablish the connection.

The Rock-to-EW module supports simultaneous connections from more than one "import" client.  Each connection operates via a separate listen-port number; see the 'ListenPortNums' parameter for configuration details.  Having each connection on a separate listen-port number allows the module to keep track of which messages have been delivered to which "import" client.

The optional 'ListenPortAddr' parameter may be used to specify a specific host address or IP to use when binding to the listen port.

When the delivery of a message to an "import" client fails, the module will delay by the 'RetryDelayMS' number of milliseconds before attempting to resend the message.

When the connection to an "import" client is lost and then restored, the module will resume the sending of messages starting with the last unsent message in the queue, provided that the queue has not overflowed and the time elapsed is not greater than the 'DropTimeoutSecs' parameter value.

Messages generated by this module are in the Earthworm TRACEBUF2 format, using the module and installation ID values specified in the 'EwModuleId' and 'EwInstallId' parameters.

The 'ChannelNames' parameter may be used to select which channels are delivered.  If any channel-name entries are specified then the channel information for each message must match a given entry, or the message will be discarded.  If no channel-name entries are specified then all messages will be delivered.  The specified channel-name entries are separated by commas, and may be in the following forms:

1. CH

2. CH.LOC

3. CH.NET.LOC

4. STA.CH.NET.LOC

5. dig1:X

The asterisk wildcard character (*) may be used to specify "match any name", and two dashes ("--") may be used to specify a null location code.  The following are example 'ChannelNames' entries:

"HNZ" : select any channel with channel name "HNZ"

"HNZ.00" : select channel with channel name "HNZ" and location "00"

"HNZ.KM.00" : channel name "HNZ", network "KM" and location "00"

"KMI.HNZ.KM.00" : station "KMI", channel "HNZ", network "KM" and location "00"

"dig1:3" : select third channel configured on instrument

"KMI.HNZ.*.00" : station "KMI", channel "HNZ", any network, and location "00"

"KMI.HNZ.KM.--" : station "KMI", channel "HNZ", network "KM" and no location

Multiple entries may be specified, for example:

"HNZ,HNN,HNE"

"KMI.HNZ.KM.00,KMI.HNN.KM.00"

"dig1:4,dig1:5"

"HNZ,KMI.HNN.KM.00,dig1:5"

 

The 'SohChansEnabledFlag' parameter may be set 'true' to enable the sending of state-of-health channels.  The availability of these channels on the instrument can be configured using ROCKTalk (or the web interface), usually via the "dig 1, Ch 1, Rock Data Interface" parameters.  The state-of-health channels are shown below, with the channel-ID names in quotes (i.e., "deg").

SOH Name      Default   Scale        Description

Temperature    true     x10      Temperature stream as "deg"

Humidity       true     x10      Humidity stream as "hum"

VofV12Batt     false    x1000    VofV12Batt stream as "vvb"

VofSysPwr      true     x1000    System voltage stream as "vep"

IofSysPwr      false    x1000    System current stream as "vec"

TimeQual       true     x1       Time quality stream as "lcq"

LoadAverage    true     x100     CPU Load Average stream as "cpu"

PercentUsed    false    x100     Percent of Data Storage Used stream as "dsk"

MassPos1       false    x1000    Mass position stream as "um#1"

MassPos2       false    x1000    Mass position stream as "um#2"

MassPos3       false    x1000    Mass position stream as "um#3"

TCXODAC        false    x1       TCXO DAC stream as "vco"

TCXODrift      false    x1       Clock phase stream as "lce" (ns)

UserStat       false    x1       User status stream as "usr"

The module writes its version number to the file "/var/log/versions/rockhound-ISTI-RockToEW" on the instrument, and this information may be viewed by typing "versions" at the Linux command prompt.

During the first 10 seconds after the module starts up, warning and debug messages will be sent to both the console and the "SMARTSLog.txt" log file.  After 10 seconds, messages will only be sent to the "SMARTSLog.txt" log file.  This is to prevent the possibility of repetitive console messages interfering with console-command operations (i.e., communications with the ROCKTalk program).

All debug messages are sent to the "SMARTSLog.txt" log file, and the following debug-mask values are supported:

Debug mask 0x0001  =   Debug level 1 (basic debug output)

Debug mask 0x0002  =   Debug level 2 (more debug output)

Debug mask 0x0004  =   Debug level 3 (even more debug output)

Debug mask 0x0008  =   Debug level 4 (verbose, per-message debug output)

 

Category: DATARELAY 
Publishes: Output
Subscribes to: RECORDER_Output

and/or CONTINUOUSRECORDER_Output

and/or KMITESTRECORDER_Output

and/or DATAINTEGRATOR_Output

and/or CHANNELDATASOURCE_Output

 

Parameters added to module specific .cfg file:

Earthworm module ID number

Name: EwModuleId
Type: int
Range: 1 to 255
Default: 99
Example: EwModuleId=99

Earthworm installation ID number

Name: EwInstallId
Type: int
Range: 1 to 255
Default: 255
Example: EwInstallId=255

Optional listen-port host address or IP

Name: ListenPortAddr
Type: String
Range: 0 to 128 characters
Default: none
Example: ListenPortAddr=192.168.0.10

List of listen-port numbers (comma-separated)

Name: ListenPortNums
Type: String
Range: 1 to 128 characters
Default: 16005
Example: ListenPortNums=16005,16006,16007

Maximum number of messages in queue (0 = no limit)

Name: MaxQueueSize
Type: int
Range: 0 to 9999999
Default: 100
Example: MaxQueueSize=99

List of specifiers for channels to be sent (comma-separated, empty = send all)

Name: ChannelNames
Type: String
Range: 1 to 4096 characters
Default: none
Example: ChannelNames=HNZ.00,HNN.00

Enable sending of state-of-health channels

Name: SohChansEnabledFlag
Type: boolean
Default: false
Example: SohChansEnabledFlag=true

Interval between sent heartbeat messages (seconds)

Name: SendAliveIntvlSecs
Type: int
Range: 0 to 9999
Default: 30
Example: SendAliveIntvlSecs=30

Text of sent heartbeat messages

Name: SendAliveMsgText
Type: String
Range: 0 to 128 characters
Default: alive
Example: SendAliveMsgText=alive

Maximum interval between received heartbeat messages (seconds)

Name: RecvAliveIntvlSecs
Type: int
Range: 0 to 9999
Default: 150
Example: RecvAliveIntvlSecs=150

Expected text of received heartbeat messages

Name: RecvAliveMsgText
Type: String
Range: 0 to 128 characters
Default: alive
Example: RecvAliveMsgText=alive

Retry delay after failed message sends (milliseconds)

Name: RetryDelayMS
Type: int
Range: 0 to 9999999
Default: 2000
Example: RetryDelayMS=2000

Disconnect time after which queuing is dropped (seconds)

Name: DropTimeoutSecs
Type: int
Range: 0 to 9999999
Default: 300
Example: DropTimeoutSecs=300

____________________________________________________________________________

 

 

The Rock-to-EW entries for the Rockhound 'modules.cfg' file are as follows:

 

Type=RockToEW

Category=DATARELAY

Descr=Rock-to-EW Data Relay

Help=Converts instrument data into a stream of Earthworm TRACEBUF messages, delivered via a TCP/IP port

Subscribes=CHANNELDATASOURCE~Output

Config=EwModuleId|int||99|1|255|0|Earthworm Module ID|Earthworm module ID number

Config=EwInstallId|int||255|1|255|0|Earthworm Install ID|Earthworm installation ID number

Config=ListenPortAddr|String|||0|128||Listen Port Address|Optional listen-port host address or IP

Config=ListenPortNums|String||16005|1|128||Listen Port Numbers|List of listen-port numbers (comma-separated)

Config=MaxQueueSize|int||100|0|9999999|0|Maximum Queue Size|Maximum number of messages in queue (0 = no limit)

Config=ChannelNames|String|||0|4096||Channel Names|List of specifiers for channels to be sent (comma-separated, empty = send all)

Config=SohChansEnabledFlag|boolean||false||||SOH Channels Enabled|Enables sending of state-of-health channels

Config=SendAliveIntvlSecs|int||30|0|9999|0|Send Alive Interval (secs)|Interval between sent heartbeat messages (seconds)

Config=SendAliveMsgText|String||alive|0|128||Send Alive Text|Text of sent heartbeat messages

Config=RecvAliveIntvlSecs|int||150|0|9999|0|Receive Alive Interval (secs)|Maximum interval between received heartbeat messages (seconds)

Config=RecvAliveMsgText|String||alive|0|128||Receive Alive Text|Expected text of received heartbeat messages

Config=RetryDelayMS|int||2000|0|9999999|0|Retry Delay (ms)|Retry delay after failed message sends (milliseconds)

Config=DropTimeoutSecs|int||300|0|9999999|0|Drop Timeout (secs)|Disconnect time after which queuing is dropped (seconds)

MaxUses=1