Changes between Initial Version and Version 1 of q3302ew


Ignore:
Timestamp:
04/08/12 17:36:15 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • q3302ew

    v1 v1  
     1[[PageOutline]] 
     2 
     3= [wiki:Earthworm Earthworm] Module: q3302ew = 
     4'''Contributed by: ISTI''' 
     5 
     6== Function == 
     7A Quanterra Q330 data feeding program, rewritten by ISTI using Lib330 from Quanterra (not MountainAir). 
     8 
     9 
     10== Details == 
     11q3302ew is a standard Earthworm module with heartbeats and status messages for when problems arrise. The communications with the Q330 is via UDP datagram's and thus any ports used in the configuration file, must  be openned for UDP traffic on the server on which it is run. This module will work under Solaris, Linux, and Windows. 
     12 
     13 
     14== Configuration File Commands == 
     15On startup, q3302ew reads the configuration file named on the command line. As always, the configuraton file contains comments: 
     16{{{ 
     17#  marks the line as a comment (example: # This is a comment). 
     18}}} 
     19Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).  
     20 
     21=== Example Configuration File === 
     22{{{ 
     23# 
     24# q3302ew configuration file 
     25# 
     26 
     27## The following items are typical Earthworm items 
     28 
     29 ModuleId       MOD_Q3302EW     # module id for this module.  Make sure to 
     30                                # add this to earthworm.h if it is not already 
     31                                # there 
     32 
     33 RingName       WAVE_RING       # transport ring to use for input/output, 
     34 
     35 HeartbeatInt   10              # Heartbeat interval in seconds 
     36                   
     37 LogFile        1               # If 0, don't write logfile;; if 1, do 
     38                                # if 2, log to module log but not stderr/stdout 
     39 
     40## The following items tell us how to talk to the Q330 
     41 
     42IPAddress               192.168.1.166           # The Q330 IP address 
     43BasePort                5330                    # The Q330 base port 
     44DataPort                1                       # Which Q330 dataport to use 
     45SerialNumber            0x010000069a412636      # The serial number of the Q330 
     46AuthCode                0x0                     # The Q330 auth code 
     47 
     48## The following items may help traversing some firewalls 
     49 
     50SourcePortControl       9999    # UDP port to use as a source, when talking to 
     51                                # the Q330's control port 
     52 
     53SourcePortData          9998    # UDP port to use as a source when talking to 
     54                                # the Q330's data port 
     55 
     56 
     57## The following items help control the log verbosity 
     58 
     59LogLevel        sd, rm, vb, sm  # Comma seperated list of:  
     60                                # sd - Logs Q330 status on connect 
     61                                # cr - Logs command retries 
     62                                # rm - Pings and sends a user message 
     63                                #      to Q330 on connect/disconnect 
     64                                # vb - Logs messages for items like 
     65                                #      filter delays 
     66                                # sm - Logs 800 series messages 
     67                                # pd - Logs all packets sent/received 
     68 
     69StatusInterval  240             # time in seconds between status updates 
     70 
     71 
     72## The following items offer some control over connections 
     73 
     74FailedRegistrationsBeforeSleep  5       # How many failed connection attempts 
     75                                        # before we give it a break for a bit 
     76MinutesToSleepBeforeRetry       3       # How long should that break be? 
     77 
     78 
     79## Some options to control dutycycle 
     80## comment out to disable 
     81 
     82#Dutycycle_MaxConnectTime       10      # We'll disconnect after this many  
     83                                        # minutes of being connected 
     84#Dutycycle_BufferLevel          10      # Disconnect when the Q330's buffer is 
     85                                        # this percentage filled.        
     86#Dutycycle_SleepTime            30      # Wait this many minutes before  
     87                                        # connecting again, when we've stopped 
     88                                        # for either of the above reasons 
     89 
     90## Where should we keep our continuity files? 
     91## These will be named: Q3302EW_cont_[dot_d_filename] and have '.bint'  
     92## and '.binq' extensions.   
     93ContinuityFileDirectory /tmp 
     94}}} 
     95 
     96=== Functional Command Listing === 
     97Below are the configure commands recognized by q3302ew, grouped by the function they influence. Most of the commands are required, but several are optional. 
     98 
     99{{{ 
     100Earthworm system setup: 
     101MyModuleId      required 
     102RingName        required 
     103HeartbeatInt    required 
     104 
     105 
     106Output Control: 
     107LogFile required 
     108LogLevel        required 
     109StatusInterval  required 
     110 
     111 
     112Communications setup: 
     113IPAddress       required 
     114BasePort        required 
     115SerialNumber    required 
     116AuthCode        required 
     117SourcePortControl 
     118SourcePortData 
     119FailedRegistrationsBeforeSleep 
     120MinutesToSleepBeforeRetry 
     121Dutycycle_MaxConnectTime 
     122Dutycycle_BufferLevel 
     123Dutycycle_SleepTime 
     124 
     125 
     126Misc: 
     127ContinuityFileDirectory  Required 
     128}}} 
     129 
     130 
     131=== Alphabetical Command Listing & Description === 
     132In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description. 
     133 
     134The following list is organized by: 
     135 
     136command [argument here] 
     137 
     138'''!AuthCode [auth]''' 
     139 
     140The authcode is the authorization password to the Q330 if used. If not used, this should be set to the hex value 0x0. 
     141{{{ 
     142Default: required field 
     143Example: authcode 0x0 
     144}}} 
     145 
     146'''!BasePort [port]''' 
     147 
     148This is the base UDP port of the Q330 to be accessed (typically 5330). 
     149{{{ 
     150baseport 5330 
     151}}} 
     152 
     153'''!ContinuityFileDirectory [path]''' 
     154 
     155This defines where continuity files should be written. This helps the system re-establish data continuity after restarts etc...[[BR]] 
     156These files will be written to the current working directory of the Q3302EW process unless otherwise configured here. 
     157{{{ 
     158    Default: the current working directory of the q3302ew process 
     159    Example: ContinuityFileDirectory /tmp 
     160}}} 
     161 
     162'''IPAddress [dpnum]''' 
     163 
     164This is the Q330 dataport to be accessed. Valid values are 1, 2, 3, 4 
     165{{{ 
     166    Default: none, required option 
     167    Example: DataPort 1 
     168}}} 
     169 
     170'''!Dutycycle_BufferLevel [pcnt]''' 
     171 
     172When the Q330's buffer level is down to pcnt percent filled, disconnect and wait for the number of minutes configured in !Dutycycle_SleepTime before reconnecting and drawing the buffer back down to pcnt again. 
     173 
     174Comment out to disable. 
     175{{{ 
     176    Default: none 
     177    Example: Dutycycle_BufferLevel 10 
     178}}} 
     179   
     180'''!Dutycycle_MaxConnectTime [minutes]''' 
     181 
     182After retrieving data from the Q330 for this many minutes, disconnect and wait the number of minutes configured in !Dutycycle_SleepTime before reconnecting for and retrieving data from the Q330 for this many minutes again. 
     183 
     184Comment out to disable. 
     185{{{ 
     186    Default: none 
     187    Example: Dutycycle_MaxConnectTime 10 
     188}}} 
     189 
     190'''!Dutycycle_SleepTime [minutes]''' 
     191 
     192When data acquisition has been stopped as a result of !Dutycycle_MaxConnectTime or !Dutycycle_BufferLevel, sleep this many minutes before reconnecting again. 
     193 
     194Comment out to disable. 
     195{{{ 
     196    Default: none 
     197    Example: Dutycycle_SleepTime 30 
     198}}} 
     199 
     200'''!FailedRegistrationsBeforeSleep [num]''' 
     201 
     202Defines the number of failed registration attempts that should be made before sleeping for a period of time. After this number of failed attempts, we'll sleep for the number of minutes configured in !MinutesToSleepBeforeRetry 
     203{{{ 
     204    Default: none, required option 
     205    Example: FailedRegistrationsBeforeSleep 5 
     206}}} 
     207 
     208'''!HeartbeatInt [beat]''' 
     209 
     210This is the heartbeat interval in seconds. 
     211 
     212'''IPAddress [addr]''' 
     213                                         
     214This is the IP address of the Q330 to be accessed. On most systems, this may be a hostname as well. 
     215{{{ 
     216Default:  none, required option 
     217       
     218IPAddress 192.168.1.100 
     219}}} 
     220 
     221'''!LogFile [switch]''' 
     222 
     223Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, q3302ew will write a daily log file(s) called q3302ewxx.log_yymmdd where xx is q3302ew's config filename  and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). 
     224{{{ 
     225Default:  none 
     226}}} 
     227 
     228'''!LogLevel [lvls]''' 
     229 
     230Configure the level of detail that is added to the LOG channel by Q3302EW. The LOG channel is also decoded and sent to the logging system, so this can be very useful in debugging. "lvls" should be a comma separated list of: 
     231 
     232 * sd - Logs Q330 status on connect 
     233 * cr - Logs command retries 
     234 * rm - Pings and sends a user message to Q330 on connect/disconnect 
     235 * vb - Logs messages for items like filter delays 
     236 * sm - Logs 800 series messages 
     237 * pd - Logs all packets sent/received 
     238{{{ 
     239    Default: none, required option 
     240    Example: LogLevel sd, rm, vb, sm 
     241}}} 
     242 
     243'''!MinutesToSleepBeforeRetry [num]''' 
     244 
     245After the number of failed registration attempts configured in !FailedRegistrationsBeforeSleep, Q3302EW will sleep for this many minutes before trying to connect and register successfully. 
     246{{{ 
     247    Default: none, required option 
     248    Example: MinutesToSleepBeforeRetry 3 
     249}}} 
     250 
     251'''!MyModuleId [mod_id]''' 
     252 
     253Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number. 
     254{{{ 
     255Default:  none                           
     256Calnet:   MyModuleId MOD_Q2EW 
     257}}} 
     258 
     259'''!RingName [ring]''' 
     260 
     261This is the ring into which the waveforms and messages are sent. 
     262{{{ 
     263Default:  none, required option                          
     264Example: RingName WAVE_RING 
     265}}} 
     266 
     267'''!SerialNumber [num]''' 
     268 
     269This is the serial number of the Q330 to be accessed. This is needed for the authentication handshaking. This is a hex value and must be preceeded with an 0x. 
     270{{{ 
     271Default: none, required option 
     272Example: 0x010000069A37E501 
     273}}} 
     274 
     275'''!SourcePortControl [port]''' 
     276 
     277This option forces the source port of the control connection to the Q330 to a particular value. This may be useful to negotiate firewalls that restrict outgoing ports. Leaving this option commented out will cause the system to assign an available port, which is the recomended setting. 
     278{{{ 
     279    Default: Use system assigned source port (typical) 
     280    Example: SourcePortControl 9999 
     281}}} 
     282 
     283'''!SourcePortData [port]''' 
     284 
     285This option forces the source port of the data connection to the Q330 to a particular value. This may be useful to negotiate firewalls that restrict outgoing ports. Leaving this option commented out will cause the system to assign an available port, which is the recomended setting. 
     286{{{ 
     287    Default: Use system assigned source port (typical) 
     288    Example: SourcePortData 9998 
     289}}} 
     290 
     291!StatusInterval [secs] 
     292 
     293This is the frequency, in seconds, to display status checkpoints in the logfile 
     294{{{ 
     295Default: none, this is required  
     296Example: StatusInterval 120 
     297}}} 
     298 
     299=== Descriptor File Example === 
     300Here is a copy of the q3302ew.desc file as implemented.  
     301 
     302{{{ 
     303modName  q3302ew 
     304modId    MOD_Q3302EW 
     305instId   INST_UNKNOWN 
     306 
     307restartMe       # restart  
     308 
     309# 
     310#    Heartbeat Specification.  If the status manager does not receive 
     311#    a heartbeat message every  seconds from this module, an 
     312#    error will be reported (client module dead).   is the maximum 
     313#    number of pager messages that will be reported and  is the 
     314#    maximum number of email messages that will be reported.  If the 
     315#    page or mail limit is exceeded, no further errors will be reported 
     316#    until the status manager is restarted. 
     317# 
     318tsec: 20  page: 0  mail: 99 
     319}}} 
     320 
     321 
     322== Helpful Hints == 
     323 
     324 
     325