• Antelope Release 5.1-64 Mac OS X 10.6.6 2011-04-28

 

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

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:

At the beginning of the parameter file there are a set of program global parameters as follows:

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.

Default parameter values for the dataloggers are defined below.

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.

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.

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

SEE ALSO

dlmon(1)

AUTHOR

Danny Harvey
Boulder Real Time Technologies, Inc.
Printer icon