# q3302ew Configuration File Commands

(last revised 4 Apr 2007)
Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description
4. Descriptor file example

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!).

## 1. 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

## 2. 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

## 3. ALPHABETIC 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.

    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

> ## 4. 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

> Module Index | q3302ew Overview