wiki:q3302ew
Last modified 8 years ago Last modified on 04/08/12 20:38:48

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

Helpful Hints