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