Rockhound to Earthworm Data Relay

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 name 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.

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 channel names to be sent (comma-separated, empty = send all)

Name: ChannelNames
Type: String
Range: 1 to 128 characters
Default: none
Example: ChannelNames=C1,C2

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|128||Channel Names|List of channel names to be sent (comma-separated, empty = send all)

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