NAME
altus2orb - transfer data from an Altus datalogger or Altus emulator to an orb
SYNOPSIS
altus2orb [-pf pfname] [-db calibdb] [-dlclock dlname] [-v]
[-state statefile] [-start starttime]
targetname orbtag1 orbname1 [orbtag2 orbname2 [...]]
DESCRIPTION
altus2orb is a program for interacting with one or more Kinemetrics Altus dataloggers or Kinemetrics Rock dataloggers,
through a bank of direct serial connections, telephone modems or ip devices,
such as terminal servers, routers or device servers, using the legacy Altus communications protocol.
Data packets along with log messages, status messages
and event summary messages are written to an output orb. Optionally,
the raw Kinemetrics .EVT files may also be written to disk.
altus2orb is capable
of supporting all block mode data transfers including continuous
streaming mode and both the dialout and dialin event triggered modes of
the Kinemetrics Altus dataloggers. Remote command and control of the dataloggers
is accomplished through orb-based command/response packet communications
using
dlcmd(1).
altus2orb supports the entire Kinemetrics Altus product line
as well as the entire Kinemetrics Rock product line through the Rockhound Altus emulator.
Note that the old
k22orb program is deprecated, should not be used and will not be supported in the future.
All Kinemetrics Altus/Rock products should be serviced exclusively with
altus2orb.
OPTIONS
-
-pf pfname
Name of program parameter file. This argument is optional and
if not specified defaults to altus2orb.
The actual parameter file name is pfname.pf.
-
-db calibdb
Name of a database that contains the calib, calper and
segtype information. These are filled into the raw data
packets before they are written to the output ORB. The
table needed is calibration.
-
-dlclock dlname
This can be used to specify by datalogger name, dlname, of the
Altus datalogger that should be used to retrieve time for the purpose of driving
a local ntpd to set the local system time.
-
-v
verbose output flag.
-
-state statefile
Name of a file to house state information. The only state information
used is the time of the last sample of waveform data that was
successfully transferred from a digitizer to the output orb. This time
for each digitizer is read from the state file at start-up and is used
to determine which events need to be transferred. This file is automatically
updated whenever an event has been successfully transferred.
-
-start starttime
A time used to determine which events need to be transferred from
the digitizers. If this argument is specified, then it supersedes
the information from the -state argument. Only events with waveform
data after starttime are transferred.
-
targetname
This is used to uniquely identify this particular instance of
altus2orb and is placed in the command, status and log ORB source
names.
This argument is required.
-
orbtag1 orbname1 [orbtag2 orbname2 [...]]
These orbtag-orbname pairs define a set of ORBs that will be used
for ORB-based input/output. This provides a generalized mechanism for
routing particular ORB packet types to particular ORBs. Each pair should correspond to different
running ORBs that will be used by altus2orb. The orbtagN values
are just unique character string tokens that are referenced in the parameter
file to define each of the ORBs.
A typical orbtag name, in
fact the name that would be used with the parameter file example described below, would
be dataorb.
The orbnameN are the corresponding
ORB names and should follow normal ORB naming conventions.
At least one orbtag-orbname pair is required.
MODEMS, DATALOGGERS AND COMMUNICATIONS
There are many different communications modes and topologies that can be
used to implement a seismic network using Altus/Rock dataloggers with
altus2orb.
Regardless of the datalogger and
altus2orb configurations and the datalogger and
altus2orb firmware
and software, there are a number of factors that will determine the effectiveness of
the network, especially for large felt earthquakes that would trigger many of the
dataloggers at close to the same times. The most important of these factors are the degree
of communications parallelization across dataloggers, the communications speed and the communications reliability.
Communications parallelization refers to the number of simultaneous communications channels that can be maintained
between the data center, where altus2orb is running, and the individual remote dataloggers. A system with
a high degree of parallelization would be one in which each datalogger-altus2orb communication channel
could operate simultaneously and independently, such as a TCP/IP based communication system where multiplexed simultaneous
communications between all dataloggers and the data center would be possible. A system with a low degree of parallelization would be one in which
a few communications channels would have to service all of the remote dataloggers, such as communications through a
small number of telephone modems (small relative to the number of dataloggers) at the data center. This is probably
the most important single factor that will determine the network effectiveness.
Note that continuous recording systems require a high degree of communications parallelization to work properly.
However, an event driven system can, in theory, operate at some level with a low degree of communications
parallelization. The problem with such systems is that they will break down at the time when they are
most needed; recording events from a large earthquake. Large earthquakes are about the only phenomena that
can cause large numbers of remote dataloggers to produce triggered events at close to the same time and this
will, by its nature, happen infrequently. A flood of events from dataloggers across the network will compete
with each other for the small communication resource at the data center resulting in a bottleneck that will
delay the acquisition of the needed data. There is no magic in the altus2orb software or the datalogger
firmware that can prevent this problem; it can only be fixed by re-engineering the communications infrastructure
to remove the communications bottleneck.
Communications speed and reliability are obviously also important factors in determining overall network effectiveness.
Analog based telephone communications provide relatively slow speeds and low levels of reliability compared to
any form of digital communications. This tends to exacerbate the parallelization problem with telephone based communications
when large events can swamp the system.
Because of the variety of communications modes supported by the Altus/Rock dataloggers, the altus2orb
configuration is necessarily complex. altus2orb maintains a set of asynchronous threads that service
abstractions known as "modems" and "dataloggers". A "modem" thread within altus2orb services a single, generally duplex,
communication link available to the host computer where altus2orb is running. This link can be a TCP/IP
client socket where the thread makes a TCP/IP connection to a known server on the internet, or it can be a connection
to a serial device that is directly connected to the host computer, such as a telephone modem or directly to a datalogger
through its serial port. Since direct serial connections to host computers are becoming rare, altus2orb will
support serial communications that are tunneled through TCP/IP client sockets, such as communications with a
local bank of telephone modems through a set of TCP/IP socket connections using a device server as a serial-TCP/IP
bridge. For communications that do not use telephone modems at all, it is possible for an altus2orb modem
thread to make a TCP/IP client connection to a device server that is co-located with a datalogger; this will
implement a very highly parallelized communications mode that is suitable for continuous communications and
would be impervious to the bottleneck problems described previously. This mode of communication works especially well with the
new Rock dataloggers since they have embedded device server capabilities, whereas the legacy Altus dataloggers
would require an extra piece of equipment (a device server) in the field.
There are separate threads running simultaneously for each datalogger that needs to be serviced. Each datalogger thread
is paired with a physical datalogger in the field through its model name (e.g. Etna, K2, ROCK) and its
serial number. Mappings to actual station and channel codes are done within each datalogger thread. All datalogger
threads connect to the physical dataloggers in the field through the modem threads. These datalogger to modem connections can be configured
as one-to-one connections, where a particular datalogger thread always uses a particular modem thread, or the connections
can be dynamically assigned. An example of a dynamic connection is when a modem thread has been configured to "listen"
for incoming calls from the dataloggers in the field. When a call is received, the modem thread determines which
datalogger has called, by querying its model name and serial number, and then makes a dynamic connection to the appropriate
datalogger thread. Once a connection from a physical datalogger in the field has been made with an altus2orb datalogger
thread through one of the altus2orb modem threads, commands can be sent to the datalogger and both event and streaming
data can be acquired by altus2orb. When there are no more commands to send and the data acquisition has finished, the physical connection
to the datalogger in the field is shut down, the virtual connection between the altus2orb modem and datalogger threads is dissolved
and the modem thread becomes available again for other connections.
Note that when we say "dialin" and "dialout", these are usually in relation to where altus2orb is running and not to the dataloggers
in the field. Therefore, a dialin connection to a modem thread would be a dialout on the physical datalogger end of the connection.
ORB OUTPUT AND INPUT PACKETS
altus2orb writes out waveform data in either GENC (generic compressed) or MGENC
(multiplexed generic compressed) packet formats,
as specified by the parameter file. (Note that these are the only output formats
that are supported at this time.) For each datalogger, individual SEED channels may be either preserved
as individual ORB packets, or they may be multiplexed together in an arbitrary fashion.
altus2orb can be
configured to package waveform data into ORB packets of arbitrary time duration.
altus2orb
allows for specification of a subcode in
the source name for each packet type (see
join_srcname(3)) so that multiplexed
packets with different collections of channels from the same datalogger can
be uniquely identified through their ORB source names.
altus2orb writes out a set of log messages as <targetname>/log packets, for
log messages relating to the altus2orb instance and as <dlname>/log
packets, for log messages relating to Q330 dataloggers. These messages are simple ASCII strings.
These log messages can be displayed by the program dlmon(1) and can be archived with orb2logs(1).
altus2orb keeps a set of status information for each attached datalogger.
All of this status information is written as a parameter file
packet (with ORB packet source name <targetname>/pf/st) to the output orb
at regular intervals.
These status packets can be displayed by the program dlmon(1).
Whenever a new connection is established to a digitizer and new
events are being requested, altus2orb puts out event summary information
as parameter file packets (with name <targetname>/pf/evtinfo). These
event summary packets are transferred to the output orb immediately
upon connection to the digitizer and are independent of the actual
waveform transfers.
Commands to altus2orb and to the attached dataloggers are all
read by altus2orb from the command ORB. The ORB packet naming conventions
for commands and command responses are discussed in the section COMMANDS.
PROGRAM PARAMETER FILE
The
altus2orb parameter file contains all of the information
necessary for connecting to various modems (or device servers)
and from there to the digitizers.
Following is an example
altus2orb parameter file.
#
# This altus2orb parameter file is used to specify all of the settings needed to
# communicate with a set of altus dataloggers.
#
status_interval 20.0 # status reporting interval in seconds
datarate_interval 20.0 # datarate calculation interval in seconds
evt_file_dir /b2/test/altus/evt # root directory for .evt files
connect_listen_string ATDT
connect_response_strings CONNECT<r><n><sl=1>CONNECT<r><n><sl=1>CONNECT<r><n>
cmd_orbtag dataorb # command line orb tag for command packets
log_orbtag dataorb # command line orb tag for log packets
status_orbtag dataorb # command line orb tag for status packets
evtinfo_orbtag dataorb # command line orb tag for evtinfo packets
packet_defs &Arr{ # ORB data packet definitions
mstr &Arr{ # streaming waveform packets
data_orbtag dataorb # command line orb tag for data packets
twin 10 # output packet time window
multiplexed yes # Is this packet channel-wise multiplexed?
suffix MGENC # data type
subcode MSTR # subcode fields in ORB srcname
}
str &Arr{ # streaming waveform packets
data_orbtag dataorb # command line orb tag for data packets
twin 10 # output packet time window
multiplexed no # Is this packet channel-wise multiplexed?
suffix GENC # data type
subcode STR # subcode fields in ORB srcname
}
mev &Arr{ # event waveform packets
data_orbtag dataorb # command line orb tag for data packets
twin 20 # output packet time window
multiplexed yes # Is this packet channel-wise multiplexed?
suffix MGENC # data type
subcode MEV # subcode fields in ORB srcname
}
ev &Arr{ # event waveform packets
data_orbtag dataorb # command line orb tag for data packets
twin 20 # output packet time window
multiplexed no # Is this packet channel-wise multiplexed?
suffix GENC # data type
subcode MEV # subcode fields in ORB srcname
}
msoh &Arr{ # event waveform packets
data_orbtag dataorb # command line orb tag for data packets
twin 600 # output packet time window
multiplexed yes # Is this packet channel-wise multiplexed?
suffix MGENC # data type
subcode MSOH # subcode fields in ORB srcname
}
}
# default parameters for modems
baud 19200 # default baud rate
flow rtscts # flow control for serial - "none" or "rtscts"
listen_string ATE1N1W1&C1S0=1<r> # listen modem control string
nolisten_string ATE1N1W1&C1S0=0<r> # no listen modem control string
dialout_string AT&C1S0=0&D2DT<pn><r> # call (dialout) modem control string
hangup_string ATH0<r> # hangup telephone modem control string
attention_string +++<sl=3>AT<r> # string that will get the attention of the modem
ring_rec_string <r><n>RING<r><n> # recognition string for telephone ringing
busy_rec_string <r><n>BUSY<r><n> # recognition string for telephone busy
connect_rec_string <r><n>CONNECT~<r><n> # recognition string for carrier detect
offhook_rec_string <r><n>NO CARRIER<r><n> # recognition string for carrier dropped
attention_rec_string <r><n>OK<r><n> # string that indicates modem is in command mode
timeout 10.0 # read timeout value in seconds
maxtries 3 # maximum number of tries to read data
timeout_connect 30.0 # connect timeout value in seconds
timeout_control 30.0 # timeout value in seconds for acqstop, acqstart, setparams
# default parameters for dataloggers
accept_pocs_from_dialin yes # should source ip-addresses be used as POCs from tcpserver dialin connections?
request_params_interval 60.0 # time interval for automatically requesting altus parameters
dialin_cmd status # command to execute when a dialin is received
auto_getevents yes # auto getevents mode enabled?
auto_getevents_at_startup no # auto dialout/getevents when the program first starts up?
auto_getevents_window 86400.0 # time window in seconds for automatic getevents during stream processing
evtfile_maxwaittime 60.0 # maximum wait time in seconds to wait for events in progress
dialout_if_getevents_incomplete yes # dialout if getevents incomplete
save_evt_files no # save .evt files?
auto_delete yes # auto deletion of event files after reception?
callmode_on_close yes # put datalogger in call mode before closing connection?
auto_stream no # auto streaming mode enabled?
max_strbuf 1800 # maximum size of internal streaming packets buffer
max_retran 30 # maximum pending retransmissions
order_output_data yes # time order stream output data?
samprate 100 # requested sample rate
altus_stream_timeout 30 # altus streaming timeout parameter
altus_stream_buffer_size 60 # altus streaming buffer_size parameter
debug_data 0 # data debug level
debug_data_timeout 30.0 # data debug timeout to automatically go back to level 0
debug_serial 0 # raw serial debug level
debug_serial_timeout 30.0 # raw serial debug timeout to automatically go back to level 0
v_strseq no # verbose output of stream sequences
v_strseq_timeout 30.0 # stream sequence output timeout to automatically disable
acq_matrix &Tbl{ # requested acquisition matrix
# event stream
mev mstr # pchan 0
mev mstr # pchan 1
mev mstr # pchan 2
}
pchan_map &Arr{ # these map altus physical channels to SEED net-sta-chan-loc codes
# pchan ev-net_sta_chan[_loc] str-net_sta_chan[_loc] calib calper segtype
0 $DLNET_$DLSTA_HGE_EV $DLNET_$DLSTA_HGE $DATA -1.0 A
1 $DLNET_$DLSTA_HGN_EV $DLNET_$DLSTA_HGN $DATA -1.0 A
2 $DLNET_$DLSTA_HGZ_EV $DLNET_$DLSTA_HGZ $DATA -1.0 A
}
# Following are modem parameter templates:
modem_templates &Arr{
direct &Arr{ # direct TCP/IP connections to remote terminal servers
timeout_connect 10.0 # establish connection timeout
timeout 5.0 # read timeout
}
dialin &Arr{ # dialin connections using local terminal server connected to a telephone modem
timeout_connect 30.0 # establish connection timeout
timeout 10.0 # read timeout
}
}
# Following is a list of modems:
modems &Tbl{
# modem-name com_mode modem_control dialin dialout template dev:baud|ip:port
basalt tcpclient none no yes direct 10.10.10.5:9801
cobox1 tcpclient none no yes direct mss4:3001
modem1 serial local yes yes dialin /dev/ttyb:19200
ruper tcpserver none yes no direct 19801
}
# Following are datalogger parameter templates:
datalogger_templates &Arr{
strevta &Arr{ # template for 3-channel altus units
# recording in both streaming and event mode
auto_stream yes # auto streaming mode enabled?
auto_getevents yes # auto getevents mode enabled?
callmode_on_close no # put datalogger in call mode before closing connection?
max_strbuf 2000 # maximum size of streaming packets buffer
max_retran 5 # maximum pending retransmissions
order_output_data yes # time order stream output data
altus_stream_timeout 30 # altus streaming timeout parameter
altus_stream_buffer_size 60 # altus streaming biffer_size parameter
samprate 100 # requested sample rate
debug_data 0 # data debug level
debug_data_timeout 30.0 # data debug timeout to automatically go back to level 0
save_evt_files yes # save altus evt files?
acq_matrix &Tbl{ # requested acquisition matrix
# event stream
mev 0 # pchan 0
mev 0 # pchan 1
mev str # pchan 2
}
pchan_map &Arr{ # these map altus physical channels to SEED net-sta-chan-loc codes
# pchan ev-net_sta_chan[_loc] str-net_sta_chan[_loc] calib calper segtype
0 $DLNET_$DLSTA_HGE_EV $DLNET_$DLSTA_HGE $DATA -1.0 A
1 $DLNET_$DLSTA_HGN_EV $DLNET_$DLSTA_HGN $DATA -1.0 A
2 $DLNET_$DLSTA_HGZ_EV $DLNET_$DLSTA_HGZ $DATA -1.0 A
}
}
strevtr &Arr{ # template for 3-channel rock units
# recording in both streaming and event mode
auto_stream yes # auto streaming mode enabled?
auto_getevents yes # auto getevents mode enabled?
callmode_on_close no # put datalogger in call mode before closing connection?
max_strbuf 2000 # maximum size of streaming packets buffer
max_retran 20 # maximum pending retransmissions
order_output_data yes # time order stream output data
altus_stream_timeout 30 # altus streaming timeout parameter
altus_stream_buffer_size 120 # altus streaming biffer_size parameter
samprate 1000 # requested sample rate
debug_data 1 # data debug level
debug_data_timeout 30.0 # data debug timeout to automatically go back to level 0
save_evt_files yes # save altus evt files?
pchan_map &Arr{ # these map altus physical channels to SEED net-sta-chan-loc codes
# pchan ev-net_sta_chan[_loc] str-net_sta_chan[_loc] calib calper segtype
0 $DLNET_$DLSTA_HGZ_EV $DLNET_$DLSTA_HGZ 2332 -1.0 A
1 $DLNET_$DLSTA_HGN_EV $DLNET_$DLSTA_HGN 2332 -1.0 A
2 $DLNET_$DLSTA_HGE_EV $DLNET_$DLSTA_HGE 2332 -1.0 A
}
}
evta &Arr{ # template for 3-channel altus units
# recording in event mode only
dialin_cmd status # command to execute when a dialin is received
auto_stream no # auto streaming mode enabled?
auto_getevents yes # auto getevents mode enabled?
callmode_on_close yes # put datalogger in call mode before closing connection?
debug_data 0 # data debug level
debug_data_timeout 30.0 # data debug timeout to automatically go back to level 0
save_evt_files yes # save altus evt files?
pchan_map &Arr{ # these map altus physical channels to SEED net-sta-chan-loc codes
# pchan ev-net_sta_chan[_loc] str-net_sta_chan[_loc] calib calper segtype
0 $DLNET_$DLSTA_HGE_EV $DLNET_$DLSTA_HGE $DATA -1.0 A
1 $DLNET_$DLSTA_HGN_EV $DLNET_$DLSTA_HGN $DATA -1.0 A
2 $DLNET_$DLSTA_HGZ_EV $DLNET_$DLSTA_HGZ $DATA -1.0 A
}
}
}
# Following is a list of dataloggers:
dataloggers &Tbl{
# model-serial dlname dlnet dlsta dialout_modem dialout_phone dialin template modem_template poc_name poc_value
K110 - BR K110 cobox1 7202740098 yes strevta
E3469 - - - auto -:3002 yes evta direct simid 12345
R130 - BR R130 basalt 7202740098 yes strevtr
}
# Following is a list if Point-Of-Contact Daemons
pocds &Tbl{
# orbtag srcname
dataorb altuspoc/pf/poc
}
log_poc 0 # POC logging level
There are many parameters that are used either as command strings
for telephone modems, or as recognition strings that the host
computer uses to identify a modem response. Strings of this type from
the altus2orb parameter file are processed through a special parser
that will recognize tokens for non-printing characters, such as RETURN and
NEWLINE characters, as well as tokens to indicate time sleeps
and substitute tokens for substituting telephone numbers. These
special tokens are defined as follows:
-
<r>
This is replaced with a \r RETURN character.
-
<n>
This is replaced with a \n NEWLINE character.
-
<sl=n>
This causes a n second sleep to take place when a
string is being sent to the modem.
-
<pn>
This causes a telephone number to be inserted (defined
in the dataloggers parameters)
-
~
This is used as a wildcard character in recognition strings to indicate any number of
any characters.
At the beginning of the parameter file there are a set of program global parameters as follows:
-
status_interval
This is the status reporting interval in seconds.
-
datarate_interval
This is the interval in seconds used to calculate data rate values.
-
evt_file_dir
This is the root directory path name for storing any
Kinemetrics .EVT files. Kinemetrics .EVT files are only
stored for a particular datalogger when its save_evt_files
parameter is set to yes
-
connect_listen_string
This is an ASCII string that is used to identify when a datalogger
is trying to initiate a dial connection. This is only used when a
datalogger is connected to the host computer through a direct serial
connection without using a telephone modem. Altus dataloggers normally
will issue something like a Hayes ATDT command followed by a telephone
number to initiate a dial connection.
-
connect_response_string
This is an ASCII string that is sent back to the datalogger from
the host computer after the datalogger
has tried to initiate a dial connection. This is only used when a
datalogger is connected to the host computer through a direct serial
connection without using a telephone modem. Altus dataloggers normally
will issue something like a Hayes ATDT command followed by a telephone
number to initiate a dial connection. The datalogger will then wait for
a normal modem response string, like CONNECT..., before it starts sending
its event info.
-
cmd_orbtag
This should be set to one of the orbtagN values from the altus2orb
command line arguments and is used to specify the orbserver that will be
used for incoming command request packets and outgoing command response packets.
If this is not specified, or if it is set to none, then command requests/responses
will not be processed.
-
log_orbtag
This should be set to one of the orbtagN values from the altus2orb
command line arguments and is used to specify the orbserver that will be
used for outgoing log message packets.
If this is not specified, or if it is set to none, then log messages will not be written.
-
status_orbtag
This should be set to one of the orbtagN values from the altus2orb
command line arguments and is used to specify the orbserver that will be
used for outgoing status packets.
If this is not specified, or if it is set to none, then status packets will not be written.
-
evtinfo_orbtag
This should be set to one of the orbtagN values from the altus2orb
command line arguments and is used to specify the orbserver that will be
used for outgoing event info parameter file packets.
If this is not specified, or if it is set to none, then event info packets will not be written.
-
packet_defs
This is an associative array that specifies a set of ORB data packet
definitions, that are used in the acq_matrix table (see below),
for determining how data channels are multiplexed into ORB data
packets and what ORB data packet formats are used. Each packet
definition is another associative array and the packet definitions
are indexed through a set of character string tokens that are the
keys for the packet_defs array. Each packet definition
contains the following parameters:
-
data_orbtag
This should be set to one of the orbtagN values from the altus2orb
command line arguments and is used to specify the orbserver that will be
used for outgoing data packets according to this packet definition.
-
twin
This is the duration of the output ORB packet in integer seconds.
-
multiplexed
This specifies if the packet will contain data from more than one
channel and should be one of yes or no. Note that if
this is set to yes, then the suffix parameter MUST be
set to MGENC. ORB packet source names for single-channel
data packets will be of the form net_sta_chan[_loc]/<suffix>[/<subcode>].
ORB packet source names for multiplexed data packets will be
of the form net_sta/<suffix>[/<subcode>].
-
suffix
This specifies the format of the data packet and must be one of
GENC, for generic compressed single channel or MGENC,
for multiplexed generic compressed.
-
subcode
This specifies a subcode string field (see join_srcname(3)) that will be put into the
output ORB data packet source names. If this is not specified,
then no subcode field will be used. This provides a mechanism so that multiplexed
packets with different collections of channels from the same datalogger can
be uniquely identified through their ORB source names.
After the global parameters there are two other sets of default parameters relating
to modems and dataloggers.
altus2orb manages communications
links through the modems table entries and dataloggers through the dataloggers
table entries. Generally, the relationship between modems and dataloggers is
dynamic, i.e. in typical event-oriented mode a datalogger may dial into any
available modem and a datalogger command, either internally generated or
from dlcmd(1), can initiate a dialout from any available modem to any particular
datalogger. However, for hardwired serial connections, either wire-based or
ip-based, that do not directly involve telephone modems, a fixed point-to-point
connection between a particular communication link and a particular datalogger can be
defined in the parameter file.
Default parameter values for the modems are defined below.
-
baud
This is the connection baud rate. This is only used for serial communication mode.
-
flow
This defines flow control and should be one of rtscts (usually know as "hardware" flow control) or none, for no flow control. This is only used for serial communication mode.
-
listen_string
This is the modem control string that is used
to set the modem into "answer" mode, i.e. the
modem will answer incoming telephone calls. This is
only used when the modem_control parameter is
set to local or remote
-
nolisten_string
This is the modem control string that is used
to set the modem into "no answer" mode, i.e. the
modem will ignore incoming telephone calls. This is
only used when the modem_control parameter is
set to local or remote
-
dialout_string
This is the modem control string that is used
to make a telephone call that is initiated by
altus2orb. The <pn> token must be specified
in this string, which is substituted with the datalogger
telephone number.
This is only used when the modem_control parameter is
set to local or remote
-
hangup_string
This is the modem control string that is used
to cause the modem to hang up the telephone line.
This is only used when the modem_control parameter is
set to local or remote
-
attention_string
This is the string that is used
to get the attention of the modem, i.e. to put
the modem into a mode where it recognizes incoming
characters as modem control strings.
This is only used when the modem_control parameter is
set to local or remote
-
ring_rec_string
This is a string that the modem
issues whenever it notices that an incoming call is "ringing".
altus2orb will search the incoming byte stream
from the modem for this string to recognize that
the telephone is "ringing".
This is only used when the modem_control parameter is
set to local or remote
-
busy_rec_string
This is a string that the modem
issues whenever the number it is dialing is "busy".
altus2orb will search the incoming byte stream
from the modem for this string to recognize that
the telephone is "busy".
This is only used when the modem_control parameter is
set to local or remote
-
connect_rec_string
This is a string that the modem
issues whenever the number it is dialing is "connected".
altus2orb will search the incoming byte stream
from the modem for this string to recognize that
the telephone is "connected".
This is only used when the modem_control parameter is
set to local or remote
-
offhook_rec_string
This is a string that the modem
issues whenever the telephone connection is lost
(loss of carrier on the line).
altus2orb will search the incoming byte stream
from the modem for this string to recognize that
the telephone is "offhook" and the connection is lost.
This is only used when the modem_control parameter is
set to local or remote
-
attention_rec_string
This is a string that the modem
issues in response to a modem control string (such as AT)
to indicate that it is in modem control mode and will
recognize incoming characters as modem control
strings.
This is only used when the modem_control parameter is
set to local or remote
-
timeout
This is a timeout value in seconds that is applied to
normal reads of the com link by altus2orb. This
is used whenever altus2orb is expecting a response
to a command already sent. If this timeout expires,
then a read timeout error is generated which will cause
altus2orb to either retry the command or drop the
connection, depending on the maxtries parameter below.
-
maxtries
This is the number of times that altus2orb will retry
a command when a read timeout error, or a read checksum or
crc error has occurred, before altus2orb will give up and
drop the connection. This
is used whenever altus2orb is expecting a response
to a command already sent.
-
timeout_connect
This is a timeout value in seconds that is applied to
reads of the com link by altus2orb during the com
link connection establishment. This
is used while altus2orb is in the process of making
a new connection. Telephone modems can take a considerable
amount of time before a connection is made. This timeout_connect
allows the user to accommodate this by overriding the normal read timeout with
a larger value.
-
timeout_control
This is a timeout value in seconds that is applied to
reads of the com link by altus2orb during certain
control operations where altus2orb is sending control
commands to the datalogger. The control operations that
this timeout apply to are acquisition start, acquisition stop
and setting of parameters.
These control commands can take a considerable
amount of time for the datalogger to accomplish and acknowledge. This timeout_control
allows the user to accommodate this by overriding the normal read timeout with
a larger value.
Default parameter values for the dataloggers are defined below.
-
accept_pocs_from_dialin
This should be yes or no and is used to determine if incoming
dialin connections through tcpserver modems should be used to
determine the ip-addresses of remote device servers attached to the remote dataloggers.
If this is yes, then the source ip-addresses from the incoming TCP/IP
connections will be automatically used for fixed point-to-point dialout connections
to the dataloggers whenever the datalogger dialout_modem is set to auto (see dataloggers
description below).
-
request_params_interval
This is the interval in seconds for automatically requesting
all datalogger parameters and status during streaming mode only.
These values are used to populate the status monitoring packets.
Note that parameters are always acquired when connections to
datalogers are first established.
-
dialin_cmd
This should be one of getevents, strstart, or status and is the
command that is executed by altus2orb whenever a dialin
connection is made. The getevents command will cause altus2orb
to query and retrieve the datalogger .EVT files. The strstart
will cause altus2orb to go into streaming data mode.
The status command will just get the datalogger status and its parameters, subject
to how the auto_getevents parameter is set.
-
auto_getevents
If this is specified as yes then altus2orb will automatically try to process
a getevents command to that datalogger every auto_getevents_window seconds when in streaming mode and/or whenever a datalogger
event is detected during any other times when there are active communications links. A getevents
command causes altus2orb to enter into a complex interaction with a
target datalogger that is intended to query the datalogger for the existence of
new events (as .EVT files), wait for events in progress, quickly acquire event
summary information and write to the output orb, acquire the new event waveforms
as .EVT file images, packetize and reformat the event waveforms into orb packets, write
the orb packets to the output orb, optionally write the verbatim .EVT files to local
disk and optionally delete the .EVT files on the remote datalogger.
-
auto_getevents_at_startup
If this is specified as yes then altus2orb will automatically establish a dialout
connection with the datalogger and issue a getevents command when altus2orb
is first started.
-
auto_getevents_window
This is a time duration in seconds that causes automatic getevents
commands to be generated every auto_getevents_window seconds
during stream mode acquisition. If this is 0, then automatic
getevents based upon a timer during streaming acquisition is disabled.
-
evtfile_maxwaittime
This is the maximum time in seconds that altus2orb will wait for
an apparent "pending" datalogger .EVT file to become available for
acquisition. altus2orb determines that an
event is in progress by looking at the alarm trigger status bit in the datalogger's status structure.
When the event file actually appears in the datalogger filesystem, altus2orb
will automatically read the file. If altus2orb waits more than evtfile_maxwaittime seconds
for a pending event, it will give up trying to acquire that event and close the connection.
-
dialout_if_getevents_incomplete
If this is specified as yes then altus2orb will automatically try to re-establish
a connection to the datalogger whenever a previous getevents command was not successfully
completed. If a prior getevents command is not successfully completed, e.g. the carrier is lost or there
are other egregious communication link errors, then this parameter can be used to
force altus2orb to repeatedly try to reconnect and finish up processing whatever .EVT
files were not processed in the original connection.
-
save_evt_files
If this is specified as yes then altus2orb will automatically copy .EVT files
to a directory on the host computer disk. The files are copied verbatim and are
suitable for processing with any programs that recognize the Kinemetrics .EVT
file format.
-
auto_delete
If this is specified as yes then altus2orb will automatically delete .EVT files
on the remote datalogger after they have been successfully acquired.
-
callmode_on_close
If this is specified as yes then altus2orb will issue a datalogger monitor
mode callmode command whenever a connection is closed. This will put the remote
datalogger into its auto-call mode so that it will send the proper modem control
strings to its telephone modem (at the remote end) and initiate calls to the host
computer whenever an event is detected. Note that this only needs to be done for
modems and dataloggers whose dialin parameters are set to yes or in situations
where a remote datalogger will be making calls to other receivers.
-
auto_stream
If this is specified as yes then altus2orb will always try to initiate
a connection to this datalogger, put it into streaming mode, continuously
acquire streaming data and write the data to the output orb. If a connection
goes down for some reason (e.g. the carrier is lost or other communication
link fatal error), then altus2orb will repeatedly attempt to reconnect
and restart the streaming acquisition. While in streaming acquisition mode,
altus2orb will continue to respond to other commands that may be sent
to the datalogger (i.e. from dlcmd(1)) by interleaving these commands into
the data stream without the need to stop and/or reset the streaming acquisition.
-
max_strbuf
This is the maximum size of the internal streaming packets buffer in data packets
for this datalogger. This must accommodate any attempts at retransmission of streaming
data packets that were not received properly and should optimally be set to correspond
approximately to the size of the streaming buffer within the remote datalogger.
-
max_retran
This is the maximum number of retransmission requests at any instant of time
in packets for this datalogger. The Altus dataloggers can queue up retransmission
requests which can be useful in cases where there is a long round-trip delay
between requests and responses. This controls how many retransmission requests
should ever be in the queue.
-
order_output_data
If this is specified as yes then altus2orb will output streaming waveform
packet data in increasing time order to the output orb by holding packets in
the internal streaming data buffer (see max_strbuf) until either the buffer is
full or there are no time gaps prior to a particular packet. If this is set to no
then streaming data packets will be written to the output orb in whatever order
they are received.
-
samprate
This is the requested output streaming sample rate in samples
per second. Note that Altus dataloggers/firmware will only
support a certain limited set of sample rates depending on the
datalogger model and firmware. It is up to the user to make
sure that the requested sample rate is one that is supported.
-
altus_stream_timeout
This controls the mode for serial data streams, as explained in
the "Altus Block Mode Communications" manual from Kinemetrics.
Currently only Modes 1 and 2 are implemented. This parameter
determines how many packets will be transmitted by the datalogger
before a continue command must be sent back from altus2orb.
If this is set to 0, then Mode 1 communications is enabled and
the datalogger will always send data packets regardless of whether
or not continue commands are sent from the receiving host. If this
is set to a value greater than 0, then the datalogger will send
that number of packets and pause its transmission until it sees
a continue command sent back from the receiving host. Mode 3,
set with a timeout value of -1, is not currently implemented.
-
altus_stream_buffer_size
This is a buffer size value that is used to configure the
datalogger when it goes into streaming mode. This is equivalent
to setting the datalogger "SDSTREAMS BUFFER_SIZE" parameter (see
the Kinemetrics "Altus Monitor Mode Communications" manual).
-
password
This is the password for Altus dataloggers that are password protected.
Note that this parameter should not be specified for dataloggers which
have no password protection set.
-
debug_data
This is a verbosity level for causing data packet debug logging to occur.
A value of 0 disables data debug logging. A value of 3 will
cause verbose hexadecimal dumps of every blockmode packet that is
sent and received by altus2orb.
-
debug_data_timeout
This is a timeout value in seconds that will automatically reset debug_data
back to 0. If this is set to 0, then the debug logging will go on indefinitely.
-
debug_serial
This is a verbosity level for causing raw serial byte stream debug logging to occur.
A value of 0 disables serial debug logging. A value of 5 will
cause verbose hexadecimal dumps of every blockmode serial byte that is
sent and received by altus2orb.
-
debug_serial_timeout
This is a timeout value in seconds that will automatically reset debug_serial
back to 0. If this is set to 0, then the debug logging will go on indefinitely.
-
v_strseq
If this is specified as yes then altus2orb will log individual
data packet sequence numbers and all of the retransmission request control packets.
-
v_strseq_timeout
This is a timeout value in seconds that will automatically reset v_strseq
back to no. If this is set to 0, then the debug logging will go on indefinitely.
-
acq_matrix
This is a table that specifies an acquisition matrix for
each datalogger. Each row in the table represents the
Altus physical channels, starting with 0. The first column in the table specifies
which channels from event files are written out as output ORB data packets.
The second column in the table specifies which channels are acquired
when in streaming mode and written out as output ORB packets.
When an entry in the table is set to 0 in the first column,
for event files that particular channel will not be written out as ORB packets, although the channel may still appear in the .EVT files.
When an entry in the table is set to 0 in the second column,
for streaming data that particular channel will not be acquired and will not be written out as ORB packets.
Note that the streaming acquisition channel bitmap in the datalogger is set according to
how this table is specified so that, for instance, only a single channel can be configured
to appear in the datalogger's streaming buffer even though multiple channels are being
acquired for event processing.
When an entry in the table is not 0, then it must correspond to one
of the packet definition tokens in the packet_defs array
which defines how that particular channel will be
multiplexed and formatted into output ORB data packets.
-
pchan_map
This is an associative array that specifies the mapping of datalogger physical
channel numbers to SEED net_sta_chan[_loc] codes, for both event and streaming data.
Also defined in this array are how the calib,
calper and segtype parameters are determined for each output
data packet. The channel numbers (starting with 0) are used as the keys in
the pchan_map associative array (see pf(5)). The corresponding values
are the SEED net_sta_chan[_loc] codes for both event and streaming data and the calib, calper and segtype
values for each channel number.
If a SEED net code is set to $DLNET, then
the net code will be substituted from the dlnet parameter in the dataloggers
table (see below). If a SEED sta code is set to $DLSTA, then
the sta code will be substituted from the dlsta parameter in the dataloggers
table (see below). Note that the SEED loc codes can be omitted.
The calib field may be
specified as a floating number, or the string $DATA, or the string $DB.
If the calib field is specified as $DATA, then the calib value is determined
from datalogger parameters that are sent with each event file or whenever the
datalogger parameters are acquired by altus2orb (this happens for instance whenever
altus2orb initiates streaming mode). In this case, the calper and
segtype fields must be specified correctly according to the calper and
segtype field definitions in the wfdisc table using the css3.0 schema.
If the calib field is specified as $DB, the calib, calper and segtype values are determined
from the input database, as specified in the -db command line argument, using the
calibration table.
If the calib field is specified as $DB, then the calper and segtype fields
in the pchan_map array entry should be left blank.
Sets of particular modem and datalogger parameters can be defined and named in modem and datalogger templates.
A particular parameter set with a particular name can be used for a large number of different modems or dataloggers.
Note that for both modems and dataloggers a template name of default is automatically assigned, and can be used in
the modems and dataloggers tables, using the default values defined previously.
-
modem_templates
This is an associative array that specifies a set of modem
template definitions that are used in the modems table (see below)
for specifying all of the modem parameters. Each template
definition is another associative array and the template definitions
are indexed through a set of character string tokens that are the
keys for the modem_templates array. Each template definition
associative array can contain any of the parameters from the default
parameters section described above for modems. The parameter values that are
specified in each template definition override the global default
values.
-
datalogger_templates
This is an associative array that specifies a set of datalogger
template definitions that are used in the dataloggers table (see below)
for specifying all of the datalogger parameters. Each template
definition is another associative array and the template definitions
are indexed through a set of character string tokens that are the
keys for the datalogger_templates array. Each template definition
associative array can contain any of the parameters from the default
parameters section described above for dataloggers. The parameter values that are
specified in each template definition override the global default
values.
The actual definitions of modems and dataloggers are specified in the modems and dataloggers tables.
The intent of this style of parameterization is that a large number of modems and dataloggers
can be configured with a minimum of effort.
-
modems
This is a table where each row represents a single modem thread.
The fields in each row are as follows:
-
modem-name
This is an arbitrary modem thread name that is only used by altus2orb
for identifying this particular modem. This name appears in log messages.
Usually, the name would be
set to something that describes the nature of the communication link. However, any name
can be assigned as long as it is unique across modem threads.
-
com_mode
This is the basic communications mode and must be set to one of serial, tcpclient or tcpserver.
For serial com_mode, the communications take place through a serial port on the
host computer. For tcpclient com_mode, the communications take place through a client TCP/IP
connection on the host computer to a remote TCP/IP server (such as a terminal server or
a device server). For tcpclient com_mode it is assumed that the remote TCP/IP server
will eventually open a serial connection to the remote datalogger, either using a telephone modem
or directly through the datalogger's serial port. tcpserver mode establishes a TCP listener on
the local host at the specified port number which will listen for incoming TCP/IP connections that
are originated by the datalogger through equipment such as certain remote device servers. For
instance, Lantronix device servers can be configured to initiate a TCP/IP socket to
a known ip-address and port number whenever there is character traffic on the attached serial line.
There is need for only one of these TCP listeners. When a connection is accepted, the tcpserver
modem thread will launch a new virtual dialin modem thread to service that particular connection
and the thread is killed and destroyed when the dialin session is finished. In every other way, the
virtual dialin modems are like other modem threads. Note that tcpserver modem threads must
be configured with modem_control of none, dialin of yes and dialout of no.
-
modem_control
This defines how, or if, altus2orb will issue modem control strings and must be set
to one of local remote or none. If modem_control is none, then it is assumed
that there is no telephone modem in the communications link and that altus2orb
is talking to the remote datalogger through a serial connection, either directly through
a host computer serial port, or indirectly through a TCP/IP connection and a terminal
server or device server. In this case no modem control strings are sent. If modem_control
is none and the remote datalogger is configured to automatically initiate a dial
connection to the host computer upon an event, then altus2orb will mimic the remote
telephone modem that the datalogger is expecting by listening for the ATDT control
string from the datalogger, as defined by the global parameter connect_listen_string,
and responding with the CONNECT string, as defined by the global parameter
connect_response_string, so that the remote datalogger will start transmission of
the event information. If modem_control is local or remote then altus2orb
assumes that a telephone modem needs to be controlled (the modem can be attached either
to a host computer serial port or through a terminal server). In these cases the
modem control strings in the modems parameters must be specified properly. If modem_control is remote
then loss of carrier is determined solely by looking for the offhook_rec_string,
in the incoming byte stream from the modem. If modem_control is local
then loss of carrier is determined either from reception of the offhook_rec_string or
directly through the out-of-band CD (Carrier Detect) signal on the serial port.
-
dialin
Should this modem thread listen for connections initiated
by remote dataloggers on this com link (yes or no)?
-
dialout
Should this modem thread initiate connections
to remote dataloggers on this com link (yes or no)?
-
template
This is the name of one of the defined templates from the modem_templates array, or default
for the global default values. This defines all of the other modem parameters.
-
dev:baud|ip:port|port
This defines the physical communication link associated with this modem thread.
For com_mode set to serial, the syntax is <UNIX_device>:<baud> with
the <UNIX_device> being a UNIX serial device name, such as /dev/ttya, and <baud>
being the desired baud rate for the device.
For com_mode set to tcpclient, the syntax is <ip>:<port> with
the <ip> being an IPv4 address or resolvable host name, such as 10.10.10.5 or basalt.brtt.com, and <port>
being the port number for connecting to a TCP/IP server running on the remote host.
For com_mode set to tcpserver, the syntax is <port> with <port>
being the port number on which the TCP listener will listen for new connectins.
-
dataloggers
This is a table where each line represents a single datalogger thread.
The fields in each row are as follows:
-
model-serial
This identifies the particular datalogger in the field that this datalogger thread services and must
consist of a single letter, which identifies the model name, immediately followed by the datalogger
serial number. The initial model name character is as follows:
-
R
Rock datalogger
-
E
Etna Altus datalogger
-
K
K2 Altus datalogger
-
W
MtWhitney Altus datalogger
-
V
Everest Altus datalogger
-
L
Makalu Altus datalogger
-
dlname
This is an arbitrary datalogger thread name that is only used by altus2orb
for identifying this particular datalogger thread. This name appears in log messages and is used to specify the targets
of particular commands using dlcmd(1).
Usually, the name would be
set to something that describes the datalogger, such as a station code. However, any name
can be assigned as long as it is unique across datalogger threads. If dlname is specified as -,
then the datalogger thread name is automatically made from dlnet_dlsta after
any substitutions for dlnet and dlsta.
-
dlnet
This is the default SEED net (network) code for this datalogger. It is used primarily
to replace the $DLNET substitution field in the pchan_map physical
channel name mappings. If dlnet is specified as -, then the internal dlnet
is automatically set according to the datalogger model as follows:
-
ROCK
dlnet is set to RK
-
Altus Etna
dlnet is set to ET
-
Altus K2
dlnet is set to K2
-
Altus MtWhitney
dlnet is set to MW
-
Altus Everest
dlnet is set to EV
-
Altus Makalu
dlnet is set to ML
-
dlsta
This is the default SEED sta (station) code for this datalogger. It is used primarily
to replace the $DLSTA substitution field in the pchan_map physical
channel name mappings. If dlsta is specified as -, then the internal dlsta
is automatically set to the datalogger serial number.
-
dialout_modem
This is the modem-name
of the modem thread, as defined in the modems table,
for connections initiate by this datalogger thread to the remote datalogger in the field,
of auto to indicate that a fixed point-to-point tcpclient modem dialout thread will
be created automatically for this datalogger.
This can be a string that exactly
matches a single entry in the modems table, in which case a fixed
point-to-point connection will be used, or it can be a regular
UNIX expression that is matched against the all of the modems
table modem-names, in which case the first available (not busy) modem thread that
matches the expression will be used. Note that whenever a command is
targeted to a particular datalogger, altus2orb will always check
to see if a connection to that datalogger is already open, regardless
of how the connection was established. If there is an existing open
connection, then altus2orb will insert the commands into the
existing link and intercept the responses. New connections are
only made when there are no existing connections.
-
dialout_phone
For telephone oriented communication this is the telephone number of the remote datalogger for making connections
initiated by this datalogger thread to the remote datalogger in the field. This string must conform to the modem
control string syntax (e.g. for a Hayes syntax you could insert ',' characters
to cause the dialing to pause briefly) and this string replaces the appropriate
<pn> token in the dialout_string. If dialout_modem has been set to auto,
then this takes on the form of the <ip>:<port> used for the automatically generated tcpclient modem.
Note that for automatic tcpclient modems <ip> can be specified as - which indicates that the
remote ip-address is unknown and must be generated from incoming tcpserver dialin connections or
from POC messages with ip-addresses that are targeted for the datalogger using the poc_name and poc_value parameters.
-
dialin
Should this datalogger thread accept connections initiated
by the remote datalogger in the field(yes or no)?
-
template
This is the name of one of the defined templates from the datalogger_templates array, or default
for the global default values. This defines all of the other datalogger parameters.
-
modem_template
This the modem template for automatically generated tcpclient modems when dialout_modem is set to auto. This can be omitted and is ignored for non-auto dialout modems.
-
poc_name
-
poc_value
These are a key-value pair that are matched against the same key values in incoming POC messages to determine if a particular POC message
should be used to define the remote ip-address. These are only used when dialout_modem is auto and these can be omitted and are ignored for non-auto dialout modems.
-
pocds
This is an optional table that contains POC daemon thread definitions. Normally only a single POC daemon is ever needed. A new daemon thread is created for each line in the table.
The fields in each row are as follows:
-
orbtag
This should be set to one of the orbtagN values from the altus2orb
command line arguments and is used to specify the orbserver that will be
used for incoming POC packets for this POC daemon thread.
-
srcname
This is a normal ORB srcname secification that is used in an orbselect(3) call for
sifting the ORB packets that the POC daemon thread will read.
-
log_poc
POC logging level. A level of 0 disables POC logging.
Each POC daemon thread will read parameter file ORB packets that contain POC messages used to assign dynamic ip-addresses to the tcpclient
dialout modem threads that are automatically created for all dataloggers with dialout_modem specified as auto. Each POC parameter file
packet must contain at a minimum two parameters; one named srcip with the dynamic ip-address of the remote tcp-server that the tcpclient
dialout modems must connect to, and another parameter with the name specified in the poc_name parameters in the dataloggers table.
The poc_name parameter value is matched against the poc_value parameters of each of the dataloggers to determine which dataloggers should use
the srcip address.
COMMANDS
Command and response packets
altus2orb takes on the role of a command and control proxy both for itself and for all
of the Altus compatible dataloggers that it is communicating with.
altus2orb continuously looks
for special command ORB packets on the ORB specified by the
cmd_orbtag parameter.
ORB packets that are read by
altus2orb as commands are in a special parameter file format
and must have the ORB
srcname <targetname>/pf/dlcm. Packets of this type are
produced by the program
dlcmd(1). Packets with this ORB
srcname are read by
altus2orb
and their commands are executed. A single command can be directed to the
altus2orb instance
itself or to any of the Altus dataloggers that it is servicing. A typical
command packet looks like this.
#657611 'altustest/pf/dlcm': 10/07/2010 (280) 20:02:36.117 : 283 bytes
parameter file data packet
cmdtime 1286481756.1
command ping hello
delayhangup 1.00
dlnames BR_E3469
dsig 42e2855a202a5ba31192eb3f1999b2eb
hostname ruper.brtt.com
ip 10.10.10.4
reply dlcmd/pf/dlcmr
sequence BR_E3469_ruper.brtt.com_67356_0
targets altustest
types altus
username danny
The response to the command, if any, is eventually specified by the reply parameter.
In this case the responses would be placed back on the
command ORB with srcname dlcmd/pf/dlcmr. In this case the command,
specified by the command parameter, is ping, which sends a ping string to one or more dataloggers and waits for echoes of the string.
The target dataloggers
are specified in the dlnames parameter which is matched as a UNIX regular expression
against all of the datalogger names managed by the instance of altus2orb. In this
case only one datalogger will be pinged. This particular command generated the following responses.
#657615 'dlcmd/pf/dlcmr': 10/07/2010 (280) 20:02:36.118 : 341 bytes
parameter file data packet
command ping hello
disposition pending
dlcom cobox2
dlname BR_E3469
dlserial E3469
log Posting command 'ping hello' from danny at ruper.brtt.com to BR_E3469
sequence BR_E3469_ruper.brtt.com_67356_0
sequence_target ruper.brtt.com_67187_1
target altustest
thostname ruper.brtt.com
tip 10.10.10.4
tpid 67187
tusername danny
type altus
#657621 'dlcmd/pf/dlcmr': 10/07/2010 (280) 20:02:42.599 : 311 bytes
parameter file data packet
command ping hello
disposition pending
dlcom cobox2
dlname BR_E3469
dlserial E3469
log datalogger BR_E3469 connected to cobox2
sequence BR_E3469_ruper.brtt.com_67356_0
sequence_target ruper.brtt.com_67187_1
target altustest
thostname ruper.brtt.com
tip 10.10.10.4
tpid 67187
tusername danny
type altus
...
#657623 'dlcmd/pf/dlcmr': 10/07/2010 (280) 20:02:42.729 : 279 bytes
parameter file data packet
command ping hello
disposition done
dlcom cobox2
dlname BR_E3469
dlserial E3469
response hello
sequence BR_E3469_ruper.brtt.com_67356_0
sequence_target ruper.brtt.com_67187_1
target altustest
thostname ruper.brtt.com
tip 10.10.10.4
tpid 67187
tusername danny
type altus
The disposition value indicates the current status of the command processing.
A value of pending, with a log message in log, means that the command is being processed but has not completed.
If a command for a particular target datalogger has completed, there will be an appropriate
ORB command response packet with either disposition of donedl, meaning the command was successfully completed
for that datalogger, or errordl, meaning the command encountered an error for that datalogger.
When the last datalogger command has been processed the disposition will be done or error.
For our case we are commanding a single datalogger so all we see is a response packet with disposition done plus
the echoed string in response. This command therefore executed successfully.
dlcmd(1) waits on these responses and prints them out for you.
The command parameter is exactly what you type into the command line arguments
cmd [cmdarg1 [...]] in the program dlcmd(1) and can contain a typical
full command line syntax. Following is the list of commands. Note that some commands
are really directed to the altus2orb programs themselves whereas other commands
are directed to the Altus/ROCK dataloggers.
Commands directed to altus2orb
-
pingt
This command simply pings the altus2orb instance without doing anything else. A returned
disposition of done indicates that the altus2orb instance is alive and
connected.
-
quit
This command will cause the target altus2orb instance to gracefully exit after flushing
all of its buffers and saving its state. If the target altus2orb is under control of
a running rtexec script, then it will get restarted automatically. This is a simple way
to force a complete restart of altus2orb without having to log into the host where it is running.
-
set par1 val1 [par2 val2 [...]]
This causes certain internal altus2orb parameters to be set. These parameters can also be
changed by editing the parameter file for each instance of altus2orb and restarting.
-
set debug_data level
This sets the internal debug_data level (see description of debug_data in PARAMETER FILE section).
-
set debug_data_timeout seconds
This sets the internal debug_data_timeout value (see description of debug_data_timeout in PARAMETER FILE section).
-
set debug_serial level
This sets the internal debug_serial level (see description of debug_serial in PARAMETER FILE section).
-
set debug_serial_timeout seconds
This sets the internal debug_serial_timeout value (see description of debug_serial_timeout in PARAMETER FILE section).
-
set log_poc level
This sets the internal log_poc level (see description of log_poc in PARAMETER FILE section).
-
set v_strseq 0|1
This sets the internal v_strseq flag (see description of v_strseq in PARAMETER FILE section).
-
set v_strseq_timeout seconds
This sets the internal v_strseq_timeout value (see description of v_strseq_timeout in PARAMETER FILE section).
-
set request_params_interval interval
This sets the internal request_params_interval value (see description of request_params_interval in PARAMETER FILE section).
-
set order_output_data 0|1
This sets the internal order_output_data flag (see description of order_output_data in PARAMETER FILE section).
-
status | getstatus
This will solicit a status from the target datalogger.
-
lstatus
This will solicit a "long" status from the target datalogger. This is
actually the full Altus EVT file header status, but relating to the
current state of the datalogger as opposed to the state during an event recording.
-
reboot
This will cause an Altus datalogger to do a reboot (equivalent to
typing "sys res" in monitor mode).
-
erase drive
This will cause one of the Altus datalogger disk drives to be erased
(equivalent to typing "wipedisk drive" in monitor mode). drive
should be one of A:, B:, etc.
-
mcmd command
This will cause the command command to be run on the datalogger
in monitor mode. Note that user interaction is not implemented, so the user
should be careful to stick to commands that do not require interactive
input from the user.
-
getparams | getconfig
This will solicit a complete list of current operational parameters
from the target datalogger.
Char, unsigned char, long int and short int parameters are all
returned as unsigned decimal integers.
-
setparams pfile.pf
This will cause a list of Altus operational parameters to be read
from the parameter file referenced by pfile.pf and sent on to the
target datalogger. Note that the parameter file name must end in a ".pf"
to cause dlcmd(1) to automatically insert the parameter file contents into the command
ORB packet.
The parameters are in the same
form as those returned by the getparams command. No checking
is done here for parameter validity, so care should be taken to
specify the parameters properly (see the Altus documentation).
This command will cause altus2orb to 1) turn off data acquisition,
2) get the current Altus operational parameters, 3) edit the Altus
parameter structure according to the parameters specified by pfile,
4) send the edited Altus parameter structure back to the datalogger
using the Altus SETPARAMS command, 5) turn on data acquisition,
6) retrieve the new Altus operational parameters and 7) send the
new parameters back to dlcmd(1) where they will be printed on
standard out in the same manner as the getparams command.
Note that only changing parameters need to be specified.
altus2orb reads the input parameters one-by-one and edits the
existing parameter structure, so it is not necessary to specify
all of the Altus parameters.
-
getevents
This will cause altus2orb to dial out to the target datalogger
and reap all new events back to the data orb, in the same manner
as if an event caused the datalogger to dial into altus2orb.
-
acqstart
This will cause acquisition to be started on the target datalogger.
-
acqstop
This will cause acquisition to be stopped on the target datalogger.
-
strstart
This will cause the start of acquisition of continuous streaming
data. The channels acquired are according to the specifications
in the altus2orb parameter file.
-
strauto
This will cause the start of acquisition of continuous streaming
data and, in addition, put altus2orb into its auto_stream mode
for that particular datalogger (auto_stream mode causes altus2orb
to always initiate streaming whenever a connection is made to
the subject datalogger). The channels acquired are according to the specifications
in the altus2orb parameter file.
-
strpause
This will cause a pause in the acquisition of continuous streaming
data from an Altus datalogger by altus2orb. Note that the actual
streaming acquisition within the datalogger itself remains unchanged.
The data acquisition can be resumed
with a strstart command. With this command, when data acquisition
is resumed, the data stream will be back-filled (as long as the
datalogger buffer is not exceeded) and the altus2orb auto_stream mode will
remain unchanged.
-
strstop
This will cause the acquisition of continuous streaming
data from an Altus datalogger by altus2orb to be stopped and
the altus2orb auto_stream mode will be disabled. Note that the actual
streaming acquisition within the datalogger itself remains unchanged.
The data acquisition can be resumed
with strstart or strauto commands. With this command, when data acquisition
is resumed, the data stream will be back-filled (as long as the
datalogger buffer is not exceeded).
-
strdisable
This is similar to the strstop command, except that in addition
to stopping the streaming data acquisition by altus2orb and disabling
the altus2orb auto_stream mode, the actual streaming acquisition within
the datalogger itself is also stopped. This means that if acquisition
is resumed with strstart or strauto, there will be no buffer
of old data within the datalogger and a gap in the continuous data will appear.
-
ft
This will cause a functional test to be started on the target datalogger.
-
ftgetevents
This will cause a functional test to be started on the target datalogger and
for a getevents command to be automatically executed to retrieve the
results of the functional test. This can be used to avoid having the Altus
datalogger make a separate callout to report the functional test (the data
should be retrieved in the same call into the datalogger used to issue
the ft command).
-
dir dirpath
This will return a directory listing of the directory with full
pathname specified by dirpath. For convenience in the UNIX
environment, all directory name "\"'s are converted to "/"'s on
output and vice versa on input.
-
dirtree [dirpath]
This will return directory listings in a recursive fashion for
all sub-directories under dirpath. If dirpath is
not specified, then the listings will start at the root levels
of the A: and (possibly) B: drives.
For convenience in the UNIX
environment, all directory name "\"'s are converted to "/"'s on
output and vice versa on input.
-
eventinfo filepath
This will return event parameters in the form of a parameter file
on standard output for the datalogger event file specified by the
full pathname filepath.
For convenience in the UNIX
environment, all filepath name "\"'s are converted to "/"'s on
output and vice versa on input.
-
eventinfotree [dirpath]
This will return event parameters in the form of a parameter file
on standard output in a recursive fashion for all datalogger event files in the
directory specified by the full pathname dirpath and all of its sub-directories.
If dirpath is
not specified, then the event listings will start at the root levels
of the A: and (possibly) B: drives.
For convenience in the UNIX
environment, all directory name "\"'s are converted to "/"'s on
output and vice versa on input.
-
delfile filepath
This will cause the datalogger file specified by the full
pathname filepath to be deleted.
For convenience in the UNIX
environment, all filepath name "\"'s are converted to "/"'s on
output and vice versa on input.
-
deltree [dirpath [creation_time_limit]]
This will delete all files and directories
in a recursive fashion for datalogger files in the
directory specified by the full pathname dirpath and all of its sub-directories.
If dirpath is
not specified, then all files and directories on all drives are
deleted.
For convenience in the UNIX
environment, all directory name "\"'s are converted to "/"'s on
output and vice versa on input.
An optional creation_time_limit can be specified which is the file creation absolute time
used to sift out files that were created before that time for deletion. Files with creation times later
than creation_time_limit are not deleted.
SEE ALSO
dlmon(1)
AUTHOR
Danny Harvey
Boulder Real Time Technologies, Inc.