Changes between Initial Version and Version 1 of rock2ew


Ignore:
Timestamp:
03/19/12 18:11:01 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • rock2ew

    v1 v1  
     1[[PageOutline]] 
     2 
     3= [wiki:Earthworm Earthworm] Module: rock2ew = 
     4'''Contributed by: ''' 
     5 
     6== Function == 
     7Provides a data relay from a Kinemetrics-Rockhound-compatible instrument into Earthworm via export/import. (new in EW v7.3) 
     8 
     9== Details == 
     10=== Rockhound to Earthworm Data Relay === 
     11The 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. 
     12 
     13The 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. 
     14 
     15The 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. 
     16 
     17The optional 'ListenPortAddr' parameter may be used to specify a specific host address or IP to use when binding to the listen port. 
     18 
     19When 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. 
     20 
     21When 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. 
     22 
     23Messages generated by this module are in the Earthworm TRACEBUF2 format, using the module and installation ID values specified in the 'EwModuleId' and 'EwInstallId' parameters. 
     24 
     25The '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. 
     26 
     27During 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). 
     28 
     29All debug messages are sent to the "SMARTSLog.txt" log file, and the following debug-mask values are supported:[[BR]] 
     30Debug mask 0x0001  =   Debug level 1 (basic debug output)[[BR]] 
     31Debug mask 0x0002  =   Debug level 2 (more debug output)[[BR]] 
     32Debug mask 0x0004  =   Debug level 3 (even more debug output)[[BR]] 
     33Debug mask 0x0008  =   Debug level 4 (verbose, per-message debug output) 
     34  
     35 
     36Category: DATARELAY  [[BR]] 
     37Publishes: Output [[BR]] 
     38Subscribes to: RECORDER_Output[[BR]] 
     39and/or CONTINUOUSRECORDER_Output[[BR]] 
     40and/or KMITESTRECORDER_Output[[BR]] 
     41and/or DATAINTEGRATOR_Output[[BR]] 
     42and/or CHANNELDATASOURCE_Output  
     43 
     44Parameters added to module specific .cfg file: 
     45 
     46'''Earthworm module ID number'''[[BR]] 
     47Name: EwModuleId[[BR]] 
     48Type: int [[BR]] 
     49Range: 1 to 255 [[BR]] 
     50Default: 99 [[BR]] 
     51Example: EwModuleId=99 
     52 
     53'''Earthworm installation ID number'''[[BR]] 
     54Name: EwInstallId[[BR]] 
     55Type: int [[BR]] 
     56Range: 1 to 255 [[BR]] 
     57Default: 255 [[BR]] 
     58Example: EwInstallId=255 
     59 
     60'''Optional listen-port host address or IP'''[[BR]] 
     61Name: ListenPortAddr[[BR]] 
     62Type: String[[BR]] 
     63Range: 0 to 128 characters [[BR]] 
     64Default: none [[BR]] 
     65Example: ListenPortAddr=192.168.0.10 
     66 
     67'''List of listen-port numbers (comma-separated)'''[[BR]] 
     68Name: ListenPortNums [[BR]] 
     69Type: String[[BR]] 
     70Range: 1 to 128 characters [[BR]] 
     71Default: 16005 [[BR]] 
     72Example: ListenPortNums=16005,16006,16007 
     73 
     74'''Maximum number of messages in queue (0 = no limit)'''[[BR]] 
     75Name: MaxQueueSize[[BR]] 
     76Type: int [[BR]] 
     77Range: 0 to 9999999 [[BR]] 
     78Default: 100 [[BR]] 
     79Example: MaxQueueSize=99 
     80 
     81'''List of channel names to be sent (comma-separated, empty = send all)'''[[BR]] 
     82Name: ChannelNames[[BR]] 
     83Type: String [[BR]] 
     84Range: 1 to 128 characters [[BR]] 
     85Default: none[[BR]] 
     86Example: ChannelNames=C1,C2 
     87 
     88'''Interval between sent heartbeat messages (seconds)'''[[BR]] 
     89Name: SendAliveIntvlSecs[[BR]] 
     90Type: int [[BR]] 
     91Range: 0 to 9999 [[BR]] 
     92Default: 30 [[BR]] 
     93Example: SendAliveIntvlSecs=30 
     94 
     95'''Text of sent heartbeat messages'''[[BR]] 
     96Name: SendAliveMsgText[[BR]] 
     97Type: String[[BR]] 
     98Range: 0 to 128 characters [[BR]] 
     99Default: alive [[BR]] 
     100Example: SendAliveMsgText=alive 
     101 
     102'''Maximum interval between received heartbeat messages (seconds)'''[[BR]] 
     103Name: RecvAliveIntvlSecs[[BR]] 
     104Type: int [[BR]] 
     105Range: 0 to 9999 [[BR]] 
     106Default: 150 [[BR]] 
     107Example: RecvAliveIntvlSecs=150 
     108 
     109'''Expected text of received heartbeat messages'''[[BR]] 
     110Name: RecvAliveMsgText[[BR]] 
     111Type: String[[BR]] 
     112Range: 0 to 128 characters [[BR]] 
     113Default: alive [[BR]] 
     114Example: RecvAliveMsgText=alive 
     115 
     116'''Retry delay after failed message sends (milliseconds)'''[[BR]] 
     117Name: RetryDelayMS[[BR]] 
     118Type: int [[BR]] 
     119Range: 0 to 9999999 [[BR]] 
     120Default: 2000 [[BR]] 
     121Example: RetryDelayMS=2000 
     122 
     123'''Disconnect time after which queuing is dropped (seconds)'''[[BR]] 
     124Name: DropTimeoutSecs[[BR]] 
     125Type: int [[BR]] 
     126Range: 0 to 9999999 [[BR]] 
     127Default: 300 [[BR]] 
     128Example: DropTimeoutSecs=300 
     129 
     130  
     131  
     132 
     133  
     134The Rock-to-EW entries for the Rockhound 'modules.cfg' file are as follows: 
     135{{{  
     136Type=RockToEW 
     137Category=DATARELAY 
     138Descr=Rock-to-EW Data Relay 
     139Help=Converts instrument data into a stream of Earthworm TRACEBUF messages, delivered via a TCP/IP port 
     140Subscribes=CHANNELDATASOURCE~Output 
     141Config=EwModuleId|int||99|1|255|0|Earthworm Module ID|Earthworm module ID number 
     142Config=EwInstallId|int||255|1|255|0|Earthworm Install ID|Earthworm installation ID number 
     143Config=ListenPortAddr|String|||0|128||Listen Port Address|Optional listen-port host address or IP 
     144Config=ListenPortNums|String||16005|1|128||Listen Port Numbers|List of listen-port numbers (comma-separated) 
     145Config=MaxQueueSize|int||100|0|9999999|0|Maximum Queue Size|Maximum number of messages in queue (0 = no limit) 
     146Config=ChannelNames|String|||0|128||Channel Names|List of channel names to be sent (comma-separated, empty = send all) 
     147Config=SendAliveIntvlSecs|int||30|0|9999|0|Send Alive Interval (secs)|Interval between sent heartbeat messages (seconds) 
     148Config=SendAliveMsgText|String||alive|0|128||Send Alive Text|Text of sent heartbeat messages 
     149Config=RecvAliveIntvlSecs|int||150|0|9999|0|Receive Alive Interval (secs)|Maximum interval between received heartbeat messages (seconds) 
     150Config=RecvAliveMsgText|String||alive|0|128||Receive Alive Text|Expected text of received heartbeat messages 
     151Config=RetryDelayMS|int||2000|0|9999999|0|Retry Delay (ms)|Retry delay after failed message sends (milliseconds) 
     152Config=DropTimeoutSecs|int||300|0|9999999|0|Drop Timeout (secs)|Disconnect time after which queuing is dropped (seconds) 
     153MaxUses=1 
     154}}} 
     155 
     156== Helpful Hints ==