Rockhound to SeedLink Data Relay

The Rock-to-SeedLink module provides a data relay to SeedLink-client programs.   It converts instrument data into 'miniSEED' messages, delivering them using SeedLink protocol via a TCP/IP port.

The Rock-to-SeedLink module supports simultaneous connections from more than one SeedLink client.  The optional 'ListenPortAddr' parameter may be used to specify a specific host address or IP to use when binding to the listen port.

A cache of processed messages is maintained in the module, and clients may request "historical" messages from the cache. The default is for the cached messages to be stored in memory. The maximum number of messages held in a memory cache (MaxCacheSize) is limited to the amount of messages that can be stored in available memory. If running Linux 2.6 or later, the maximum cache size (MaxCacheSize) is not 0 and the cache directory is specified (CacheDir), the cached messages are stored to disk. The maximum number of messages held in a disk cache (MaxCacheSize) is limited by the amount of messages that can be stored to disk. The size of the disk cache is fixed. The oldest entry is automatically overwritten when the disk cache is full. Each message requires the number of bytes in the record size (SLRecordSize which defaults to 512 bytes) plus the metadata size of 26 bytes. So by default each message would use approximately 538 bytes. Also there is a header at the beginning of the cache, which takes 17 bytes. The cache size will be (26 + SLRecordSize) x MaxCacheSize + 17.

If the cache is stored on disk the previously cached messages will be used upon startup if there are no errors detected and the cache configuration (CacheDir , MaxCacheSize, SLRecordSize) has not been altered. If the cache directory (CacheDir) is changed the old cache directory should be manually deleted.

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

The format of the 'miniSEED' messages generated by this module limits the size of the stream ID names to the following maximum lengths:

Station name:  5 characters

Channel name:  3 characters

Network name:  2 characters

Location name:  2 characters

If longer names are configured in the instrument, they will be truncated. Each channel must have a unique combination of station, channel, network and location names (SCNL.)

The per channel station code (dig1 Ch1 Station code) , channel ID (dig1 Ch1 ID), network code (dig1 Ch1 Network code) and location code (dig1 Ch1 Location code) are normally used. If the per channel station code is not specified the "Unit ID" is used and if the per channel network code is not specified the "Network ID” is used.

This module fully implements the SeedLink protocol, with the following exceptions:  The 'FETCH' command is not implemented, and only the 'ID', 'STATIONS' and 'STREAMS' level-arguments of the 'INFO' command are implemented.

The 'MiniSeedFormat' parameter selects the type of MiniSeed format used for transmitted messages.  Its value may be "STEIM1" or "STEIM2".

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-RockToSLink" 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: CHANNELDATASOURCE
_Output

 

 

Parameters added to module specific .cfg file:

Optional listen-port host address or IP

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

Listen-port number

Name: ListenPortNumber
Type: String
Range: 1 to 128 characters
Default: 18000
Example: ListenPortNumber=18000

Maximum number of simultaneous client connections allowed

Name: MaxNumConnections
Type: int
Range: 0 to 9999999
Default: 25
Example: MaxNumConnections=99

Maximum age for messages held in cache (seconds, 0 = no limit, not used for disk cache)

Name: MaxCacheAgeSecs
Type: int
Range: 0 to 9999999
Default: 3600
Example: MaxCacheAgeSecs=5000

Cache directory (Linux 2.6 or later required)

Name: CacheDir
Type: String
Range: 1 to 128 characters
Default: none for memory cache
Example: CacheDir =\data

Maximum number of messages held in cache (0 = no limit, 0 is not recommended)

Name: MaxCacheSize
Type: int
Range: 0 to
9223372036854775807
Default: 10000
Example: MaxCacheSize=20000

Maximum number of messages in queue (0 = no limit, 0 is not recommended)

Name: MaxQueueSize
Type: int
Range: 0 to 9999999
Default: 10000
Example: MaxQueueSize=20000

Retry delay after failed message sends (milliseconds)

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

List of channel names to be sent (comma-separated, empty = send all)

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

Enable sending of state-of-health channels

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

Format for transmitted MiniSeed messages (STEIM1 or STEIM2)

Name: MiniSeedFormat
Type: String
Default: STEIM2
Example: MiniSeedFormat=STEIM1

Number of samples to force miniSEED packet encode (0 = not used)

Name: SamplesForceEncode
Type: int
Range: 0 to 9999999
Default: 0
Example: SamplesForceEncode=20

The record size for SeedLink miniSEED packets

Name: SLRecordSize
Type: choice
Range:  128, 256, 512
Default: 512
Example: SLRecordSize=512

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

 

Type=RockToSLink

Category=DATARELAY

Descr=Rock-to-SeedLink Data Relay

Help=Converts instrument data into 'miniSEED' messages, delivered using SeedLink protocol via a TCP/IP port.

Subscribes=CHANNELDATASOURCE~Output

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

Config=ListenPortNumber|int||18000|0|65535|0|Listen Port Number|Listen-port number

Config=MaxNumConnections|int||25|0|9999999|0|Maximum Connections|Maximum number of simultaneous client connections allowed

Config=MaxCacheAgeSecs|int||3600|0|9999999|0|Maximum Cache Age (secs)|Maximum age for messages held in cache (seconds, 0 = no limit)

Config=CacheDir|String|||0|128||Cache directory|Optional Cache directory (empty for memory cache)

Config=MaxCacheSize|int||10000|0|9223372036854775807|0|Maximum Cache Size|Maximum number of messages held in cache (0 = no limit)

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

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

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

Config=SLRecordSize|choice||512|128~256~512|||Seed Link Record Size|Record Size for Seed Link packets.

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

Config=MiniSeedFormat|String||STEIM2|0|10||MiniSeed Format|Format for transmitted MiniSeed messages (STEIM1 or STEIM2)

Config=SamplesForceEncode|int||0|0|9999999|0|Samples Force Encode|Number of samples to force miniSEED packet encode (0 = not used)

MaxUses=1