On startup, k2ew reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm k2ew module. In the control file, lines may begin with a valid k2ew command (listed below) or with one of 2 special characters:
Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). Blank lines are also permitted in the control file.# marks the line as a comment (example: # This is a comment).
@ allows control files to be nested; one control file can be accessed from another with the command "@" followed by a string representing the path name of the next control file (example: @model.d).
Below are the commands recognized by k2ew, grouped by the function
they influence. Some of the commands are required, as noted. They may be specified
in any order in the control file, with the exception of the K2 communications mode settings:
these must be listed in the order shown here.
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 log file is particularly useful for k2ew because it records
status and event messages sent by the K2. These
messages also appear on the k2ew console window when running on WindowsNT.
Because of limitations in the K2, it is recommended that this value be limited
to about 120 seconds. When trying to recover from longer restarts, the K2 may
not be able to keep up with its processing. The result will be gaps in the
trace data with no accompanying gaps in packet sequence numbers.
1. FUNCTIONAL COMMAND LISTING
Earthworm system setup:
ModuleId required
RingName required
LogFile required
HeartbeatInt required
Debug optional
The two commands for any ONE of the three communication modes:
K2 communication parameters: TCP mode
TcpAddr required
TcpPort required
K2 Communications parameters: Solaris TTY mode
TtyName required
Speed required
K2 communication parameters: WindowsNT COM port
ComPort required
Speed required
k2ew buffer and timing parameters:
CommTimeout optional
MaxRestartAge optional
WaitTime optional
DontQuit optional
RestartFile optional
K2 configuration, status and alarm parameters:
Network required
BasePinno optional
StatusInterval optional
ExtStatus optional
HighTempAlarm optional
OnBattery optional
LowBattAlarm optional
LowTempAlarm optional
MinDiskKB optional
2. ALPHABETIC COMMAND LISTING & DESCRIPTION
command arg1 function
BasePinno n K2ew Configuration
Set the base pin number to n. Earthworm pin numbers are
assigned to each trace packet using this base number plus the K2 stream number,
which normally range from 0 to 5.
Default: 0
Example: BasePinno 1001
ComPort n WindowsNT COM mode
Set the WindowsNT communications port to COMn.
This command can only be used with k2ew_com on WindowsNT. K2ew supports COM
port numbers up to 256; the PC must be specially configured to use anything
besides COM port 1 or 2.
Default: none
Example: ComPort 1
CommTimeout N K2ew Buffer and Timing
Set the time k2ew will wait for communications with the K2 to
N milliseconds. If nothing is heard from the K2 in this
interval, k2ew will close the COM or TCP port, attempt to reopen this port,
and resume communicating with the K2. If this attempt is unsuccessful or
still nothing is heard from the K2, k2ew will terminate. If a
RestartFile is specified, k2ew will record all
the information it needs for a restart so that it can attempt to resume
the data stream when k2ew is restarted, such as by statmgr.
Default: 5000
Example: CommTimeout 10000
Debug N Earthworm setup
Sets the debug level to Turns on debug logging for k2ew. Level 0 is no
debug logging, level 5 is very verbose logging.
Default: 0
Example: Debug 1
DontQuit K2ew Buffer and Timing
If present, this command tells k2ew not to quit on timeout conditions while
attempting to read data from teh K2. Instead of quiting, a log entry will be
made when the timeout condition starts, and when k2ew resumes reading data
from the K2.
Default: off
Example: DontQuit
ExtStatus K2ew Status and Alarm Parameters
Request K2 `extended' status in addition to the regular status messages. See
StatusInterval for obtaining K2 status messages.
The extended status message includes temperature at the K2, last K2 restart
time, and fault indicators for K2 parameters, flash memory, RAM, DSP system.
Thresholds can be set for high and
low temperature alarms. Most (all?) K2 instruments
do not support the extended status message.
Default: off
Example: ExtStatus
HeartbeatInterval nsec Earthworm Setup
Defines the number of seconds, nsec between TYPE_HEARTBEAT
messages issued by k2ew.
Default: none
Example: HeartbeatInterval 30
HighTempAlarm N K2ew Status and Alarm Parameters
Set the threshold for the K2 high temperature N tenths
of a degree C. That is, for an alarm at 30 C, use a setting of 300 here.
When this threshold is exceeded, k2ew sends a status message to statmgr,
which can be configured to send email or pages.
Default: 1000 # (for an alarm at 100 C, essentially no alarm)
Example: HighTempAlarm 350 # For an alarm at 35.0 C
LogFile switch Earthworm Setup
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 non-zero, k2ew will write daily log file(s)
called nnnnnxx.log_yyyymmdd where nnnnn is the name of the configuration file
(with the suffix `.d' removed), xx is k2ew's module id (set with
ModuleId command) and yyyymmdd is the current UTC
date (ex: 19960123) on the system clock. The file(s)
will be written in the EW_LOG directory (environment variable).
Default: none
Example: LogFile 1
OnBattery K2ew Status and Alarm Parameters
If present, this command enables reporting of "loss of external power" alarm.
The K2 reports battery voltage in its status message. When external power is
provided, the K2 reports battery voltage as zero. Since a real battery
voltage of zero would not let the K2 do anything, this is reasonable. When
the K2 first reports battery voltage as non-zero (indicating external power
has been lost) k2ew will report this fact if this command is present. This
command applies to both internal and external batteries. But since the K2
does not normally have external power (from a 110 VAC power adapter) while
using an external battery, this command should not be used when using an
external battery. Any provision for charging an external battery is separate
from the K2 and would not be monitored by k2ew.
Default: #(no alarm)
Example: OnBattery
LowBattAlarm N K2ew Status and Alarm Parameters
Set the low battery voltage alarm threshold to N
tenths of a volt. When this threshold is exceeded, k2ew sends a status message
to statmgr, which can be configured to send email or pages. The K2 reports its
battery voltage in the status message. When the
K2 is powered from external sources, it reports the voltage as `0'. The actual
battery voltage is reported only when the K2 is running off the internal
battery. See the K2 User Manual for recommended battery voltages and
maintenance.
Default: -1 #(no alarm)
Example: LowBattAlarm 110 # (for an alarm at 11.0 Volts.)
LowTempAlarm N K2ew Status and Alarm Parameters
Set the threshold for the K2 low temperature N tenths
of a degree C. That is, for an alarm at 20 C, use a setting of 200 here.
When this threshold is exceeded, k2ew sends a status message to statmgr,
which can be configured to send email or pages.
Default: -1000 # (for an alarm at -100 C, essentially no alarm)
Example: LowTempAlarm 150 # For an alarm at 15.0 C
MaxRestartAge N K2ew Buffer and Timing
Set the maximum acceptable age of the restart file
to N seconds. When k2ew starts up, it reads the restart
file if it exists. If the restart file is younger than this limit, k2ew will
attempt to resume stream data from the K2 at the last packet k2ew sent before
last shut down. This will allow the trace data from this K2 to be sent to
earthworm in time-order, though it will be late in arriving at the earthworm
transport ring. MaxRestartAge should be less
than WaitTime.
For this restart feature to work, the K2 stream
packet sequence number must not have been reset since k2ew last wrote the
restart file.
Default: 0 # turns off use of restart file
Example: MaxRestartAge 60 # max age of restart file is 1 minute
MinDiskKB Na Nb K2ew Status and Alarms
Sets the alarm thresholds for low disk space for disk A to
Na KiloBytes and disk B to Nb
KiloBytes. When this threshold is exceeded, k2ew sends a status message
to statmgr, which can be configured to send email or pages. The K2 reports
free disk space in the status message. Some
K2s have a disk (actually a PCMCIA solid-state memory device) installed only
in slot `A'; in that case Nb should be set to -1 to
disable the alarm for that disk.
Default: -1 -1 # For no alarms
Example: MinDiskKB 500 -1 # for 500 KB on disk A and no alarm on disk B
ModuleId mod_id Earthworm setup
Sets the module id for labeling all outgoing trigger, heartbeat, and error
messages. mod_id is a character string (valid strings
are listed in earthworm.d) that relates to a unique single-byte number. In
general, a different module ID is needed for each instance of k2ew.
Default: none
Example: MyModuleId MOD_K2_SEA
Network net-code K2 Configuration
Sets the network name for earthworm trace packets to
net-code. All earthworm trace packets are identified by
their station, component, and network names (SCN). K2ew obtains the station
name from the K2. (The K2 is configured separately from k2ew; see the K2 User
Manual from Kinemetrics.) The K2 may also have its component names configured
in it. If so, k2ew will use these names; otherwise it will name the components
"CH1", "CH2", etc. The third part of the SCN is set by the Network
command.
Default: none
Example: Network "UW"
RestartFile filename K2ew Buffer and Timing
This command is used to specify the name of the restart file.
filename can be an absolute or relative (to the
EW_PARAMS directory) file name. This command, in conjunction with
MaxRestartAge
is used to control the restart
mechanism that k2ew uses with the K2. If filename is the
null string (""), or the Restart command is absent, the restart
mechanism is disabled and now restart file will be written.
The restart file name must be unique for each instance of k2ew. This is because k2ew reads the station name from this file instead of from the K2. If this file contains the wrong station name, then the trace data will be labeled incorrectly. K2ew now requests a `params' message from the K2 after starting up with a restart file. If the K2's station name does not match the name in the restart file, k2ew will write an error message and exit.
Default: "" # the null string, for no restart file Example: RestartFile "SEA.k2"
RingName ring Earthworm setup
Tells k2ew which shared memory region to use for output. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region.Default: none Example: RingName WAVE_RING
Speed N K2ew COM and TTY modes
Set the serial port speed to N bits per second. This speed must match the speed setting of whatever device is connected to the COM or TTY ports (on WindowsNT or Unix, respectively.) This may be the K2 if it is connected directly to the computer by RS-232 cable, or another device such as a Lantronix MSS100 for serial tunneling over IP. This command is required, and must follow, after either the ComPort (on WindowsNT) or the TtyName(on Unix) commands if they are used.
Default: none Example: Speed 19200
StatusInterval N K2ew Buffer and Timing
Commands k2ew to request a status message from the K2 every N minutes. If configured, the extended status message will be requested at the same time. The status message from the K2 includes K2 time, battery voltage, hardware status flag (OK/FAULT), alarm and trigger status, and disk status. All information from the status message is logged in the k2ew log file and printed to the standard-error output stream.Default: 30 Example: StatusInterval 10 # Every ten minutes
TcpAddr address K2 TCP communications
Sets the IP address of the network device that is connected to the serial port of the K2, for TCP communications mode on WindowsNT and Unix. Note that the K2 does not have a network device installed, this is a separate piece of hardware. This address can be a numerical IP address, or if your nameserver is configured, a domain name. This command can only be used with k2ew_tcp.Default: none Example: TcpAddr moonunit.seismo.podunk.edu
TcpPort N K2 TCP Communication Mode
Set TCP port number for the network device connected to the K2 to N. This is the port number for establishing communications through the network device to the K2. This command is allowed only after the TcpAddr, where it is required.Default: none Example: TcpPort 3001
TtyName tty K2 TTY Communications
Set the TTY device name to tty for establishing communications to the K2 via a serial port on a Unix computer. This command is allowed and required only for k2ew_tty on Unix. It could be used when the K2 is connected directly to the computer by an RS-232 cable, or when a device such as a Lantronix MSS100 is connected to the computer for serial tunneling over IP.Default: none Example: /dev/sts/ttyC29
WaitTime N K2ew Buffer and Timing
Set the maximum time for which k2ew will wait for packets to be resent from the K2 to N seconds. After this time limit, these packets will be skipped. K2ew will place `waiting' slots in its internal buffer to be filled when it receives the requested packets from the K2. Output from k2ew to the transport ring will wait until either the requested packet is received, the time limit expires for a waiting packet, or the number of re-send requests is exceeded. This will action ensure that trace packets are sent to other earthworm modules in time order.Default: 60 Example: WaitTime 120
# # k2ew configuration file # # This code receives serial data stream (SDS) packets from the K2 via # a TCP/IP port, converts them into Earthworm trace buf messages, and # stuffs them into a wave ring. # TcpAddr mss-1 # IP address or domain name of K2 interface TcpPort 3001 # TCP port number of K2 interface ModuleId MOD_K2EW # module id for this import RingName WAVE_RING # transport ring to use for input/output LogFile 1 # If 0, don't output to logfile HeartbeatInt 30 # Heartbeat interval in seconds Network NC # Network name for EW msg headers # Optional commands: BasePinno 1001 # Earthworm pin numbers are assigned by # adding this base number to the stream # number (0 - 5) of each packet # default: 0 # RestartFile "SEA.k2" # If you want to attempt a K2 restart, give # a name for the restart file. It MUST be # a unique name for this K2 or gross confusion # will result! # default: none MaxRestartAge 60 # Maximum age of the restart file, in seconds # If the restart file is older than this # when k2ew restarts, a normal start will # be used. # Should be less than WaitTime (below) # default: 0 (seconds) CommTimeout 5000 # If unable to communicate with K2 for X # milliseconds, retry socket or terminate # default: 5000 (milliseconds) WaitTime 60 # Maximum number of seconds to wait for a # packet to be resent from the k2 # default: 60 (seconds) StatusInterval 30 # Interval in minutes between requests for # K2 status (if 0, then no status requests) # default: 30 (minutes) OnBattery # Report when K2 loses external power and is # running on battery power. # default: do not report LowBattAlarm 110 # In tenths of volts, threshold for low # battery alarm (if -1, then no alarm) # default: -1 MinDiskKB 500 -1 # Low disk alarm threshold in Kilobytes, for # disk A and disk B (if -1, then no alarm) # default: -1 -1 ExtStatus # Request extended status with normal status # Comment this out for no extended status # default: no extended status LowTempAlarm 150 # Low temperature alarm threshold, in tenths # degree, C; default: -1000 HighTempAlarm 350 # High temperature alarm threshold, in tenths # degree, C; default: 1000 Debug 0 # debug level: 0 or commented out for no debug # logging; 1 - 4 for increasing verbosity # default: no debug output