Earthworm Module: q3302ew
Contributed by: ISTI
Function
A Quanterra Q330 data feeding program, rewritten by ISTI using Lib330 from Quanterra (not MountainAir).
Details
q3302ew 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.
Configuration File Commands
On startup, q3302ew reads the configuration file named on the command line. As always, the configuraton file contains comments:
# marks the line as a comment (example: # This is a comment).
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).
Example Configuration File
# # q3302ew configuration file # ## The following items are typical Earthworm items ModuleId MOD_Q3302EW # module id for this module. Make sure to # add this to earthworm.h if it is not already # there RingName WAVE_RING # transport ring to use for input/output, HeartbeatInt 10 # Heartbeat interval in seconds LogFile 1 # If 0, don't write logfile;; if 1, do # if 2, log to module log but not stderr/stdout ## The following items tell us how to talk to the Q330 IPAddress 192.168.1.166 # The Q330 IP address BasePort 5330 # The Q330 base port DataPort 1 # Which Q330 dataport to use SerialNumber 0x010000069a412636 # The serial number of the Q330 AuthCode 0x0 # The Q330 auth code ## The following items may help traversing some firewalls SourcePortControl 9999 # UDP port to use as a source, when talking to # the Q330's control port SourcePortData 9998 # UDP port to use as a source when talking to # the Q330's data port ## The following items help control the log verbosity LogLevel sd, rm, vb, sm # Comma seperated list of: # sd - Logs Q330 status on connect # cr - Logs command retries # rm - Pings and sends a user message # to Q330 on connect/disconnect # vb - Logs messages for items like # filter delays # sm - Logs 800 series messages # pd - Logs all packets sent/received StatusInterval 240 # time in seconds between status updates ## The following items offer some control over connections FailedRegistrationsBeforeSleep 5 # How many failed connection attempts # before we give it a break for a bit MinutesToSleepBeforeRetry 3 # How long should that break be? ## Some options to control dutycycle ## comment out to disable #Dutycycle_MaxConnectTime 10 # We'll disconnect after this many # minutes of being connected #Dutycycle_BufferLevel 10 # Disconnect when the Q330's buffer is # this percentage filled. #Dutycycle_SleepTime 30 # Wait this many minutes before # connecting again, when we've stopped # for either of the above reasons ## Where should we keep our continuity files? ## These will be named: Q3302EW_cont_[dot_d_filename] and have '.bint' ## and '.binq' extensions. ContinuityFileDirectory /tmp
Functional Command Listing
Below are the configure commands recognized by q3302ew, grouped by the function they influence. Most of the commands are required, but several are optional.
Earthworm system setup: MyModuleId required RingName required HeartbeatInt required Output Control: LogFile required LogLevel required StatusInterval required Communications setup: IPAddress required BasePort required SerialNumber required AuthCode required SourcePortControl SourcePortData FailedRegistrationsBeforeSleep MinutesToSleepBeforeRetry Dutycycle_MaxConnectTime Dutycycle_BufferLevel Dutycycle_SleepTime Misc: ContinuityFileDirectory Required
Alphabetical Command Listing & Description
In 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.
The following list is organized by:
command [argument here]
AuthCode [auth]
The authcode is the authorization password to the Q330 if used. If not used, this should be set to the hex value 0x0.
Default: required field Example: authcode 0x0
BasePort [port]
This is the base UDP port of the Q330 to be accessed (typically 5330).
baseport 5330
ContinuityFileDirectory [path]
This defines where continuity files should be written. This helps the system re-establish data continuity after restarts etc...
These files will be written to the current working directory of the Q3302EW process unless otherwise configured here.
Default: the current working directory of the q3302ew process Example: ContinuityFileDirectory /tmp
IPAddress [dpnum]
This is the Q330 dataport to be accessed. Valid values are 1, 2, 3, 4
Default: none, required option Example: DataPort 1
Dutycycle_BufferLevel [pcnt]
When 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.
Comment out to disable.
Default: none Example: Dutycycle_BufferLevel 10
Dutycycle_MaxConnectTime [minutes]
After 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.
Comment out to disable.
Default: none Example: Dutycycle_MaxConnectTime 10
Dutycycle_SleepTime [minutes]
When data acquisition has been stopped as a result of Dutycycle_MaxConnectTime or Dutycycle_BufferLevel, sleep this many minutes before reconnecting again.
Comment out to disable.
Default: none Example: Dutycycle_SleepTime 30
FailedRegistrationsBeforeSleep [num]
Defines 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
Default: none, required option Example: FailedRegistrationsBeforeSleep 5
HeartbeatInt [beat]
This is the heartbeat interval in seconds.
IPAddress [addr]
This is the IP address of the Q330 to be accessed. On most systems, this may be a hostname as well.
Default: none, required option IPAddress 192.168.1.100
LogFile [switch]
Sets 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).
Default: none
LogLevel [lvls]
Configure 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:
- sd - Logs Q330 status on connect
- cr - Logs command retries
- rm - Pings and sends a user message to Q330 on connect/disconnect
- vb - Logs messages for items like filter delays
- sm - Logs 800 series messages
- pd - Logs all packets sent/received
Default: none, required option Example: LogLevel sd, rm, vb, sm
MinutesToSleepBeforeRetry [num]
After the number of failed registration attempts configured in FailedRegistrationsBeforeSleep, Q3302EW will sleep for this many minutes before trying to connect and register successfully.
Default: none, required option Example: MinutesToSleepBeforeRetry 3
MyModuleId [mod_id]
Sets 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.
Default: none Calnet: MyModuleId MOD_Q2EW
RingName [ring]
This is the ring into which the waveforms and messages are sent.
Default: none, required option Example: RingName WAVE_RING
SerialNumber [num]
This 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.
Default: none, required option Example: 0x010000069A37E501
SourcePortControl [port]
This 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.
Default: Use system assigned source port (typical) Example: SourcePortControl 9999
SourcePortData [port]
This 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.
Default: Use system assigned source port (typical) Example: SourcePortData 9998
StatusInterval [secs]
This is the frequency, in seconds, to display status checkpoints in the logfile
Default: none, this is required Example: StatusInterval 120
Descriptor File Example
Here is a copy of the q3302ew.desc file as implemented.
modName q3302ew modId MOD_Q3302EW instId INST_UNKNOWN restartMe # restart # # Heartbeat Specification. If the status manager does not receive # a heartbeat message every seconds from this module, an # error will be reported (client module dead). is the maximum # number of pager messages that will be reported and is the # maximum number of email messages that will be reported. If the # page or mail limit is exceeded, no further errors will be reported # until the status manager is restarted. # tsec: 20 page: 0 mail: 99