README for samtac2ew, a module that takes data from the SAMTAC-802U and inserts it into Earthworm rings

SAMTAC to Earthworm Module was developed by Tim Zander at ISTI from November 2008 through January 2009, funded by Tokyo Sokushin

====HTML DOCUMENTATION AND SUPPORT====

This documentation in html format is available in the earthworm source documentation directory(ewdoc/WEB_DOC/ovr/samtac2ew_ovr.html)

For assistance please contact ISTI at http://www.isti.com/contact-info

====OVERVIEW====

This module recieves data packets from a SAMTAC-802U. The data packets are then put into an Earthworm ring-memory transport buffer. The module was developed using Earthworm version 7.2. It is all 'C' code compiled using standard makefiles ("makefile.nt") like those used with other Earthworm modules. On Windows there are two versions of SAMTAC2EW: samtac2ew_com, to use a COM port on a PC; and samtac2ew_tcp, for using TCP communications to a serial-to-TCP server connected to the serial port on the SAMTAC-802U. There is one config file for the TCP version (samtac2ew_tcp.d) and another config file for the COM version (samtac2ew_com.d.) One instance of SAMTAC2EW will be needed for each SAMTAC, and each instance will have its own config file.

SAMTAC2EW Packet Handling Details
As data packets are received from the SAMTAC the headers are read, and a SOH message is sent to earthworm. The packets are then demuxed and a tracebuf2 packets for each channel is sent to the ring buffer. If there is a break in the sequence numbers or the checksums are bad, samtac2ew will write an error message to the ring buffer.
SAMTAC2EW State Of Health Details
SAMTAC2EW will send out a State Of Health(SOH) packet at a configurable interval(default 5 minutes) or if the SOH changes. The Packet Type used is TYPE_SAMTACSOH_PACKET and this must be defined in the earthworm.d file. An example SOH packet:

ZZ-ISTI 1232641240
DeviceID: 21
Detecting Earthquake: 0
Media Capacity Alarm: 0
Power Supply Voltage Alarm: 0
GPS Alarm: 1

Where ZZ-ISTI is the Network-Station and 1232641240 is the epoch time the packet was sent. 

====CONFIGURATION====

On startup, samtac2ew reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm samtac2ew module. In the control file, lines may begin with a valid samtac2ew command (listed below) or with one of 2 special characters:

    #  marks the line as a comment (example: # This is a comment).
       
    @  allows control files to be nested; one control file can be 
       accessed from another with the command "@" followed by 
       a string representing the path name of the next control file 
       (example: @SCNL.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). Blank lines are also permitted in the control file.

1. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by samtac2ew, grouped by the function they influence. Some of the commands are required, as noted. They may be specified in any order in the control file, with the exception of the SAMTAC-802U communications mode settings: these must be listed in the order shown here.

    Earthworm system setup:
                ModuleId                required
                RingName                required
                LogFile                 required
                HeartbeatInt            required
                DeviceID                required
                Debug                   optional

    The two commands for any ONE of the two communication modes:
        SAMTAC communication parameters: TCP mode
                TcpAddr                 required
                TcpPort                 required

        SAMTAC communication parameters: Windows COM port
                ComPort                 required
                Speed                   required
 
        SAMTAC2EW buffer and timing parameters:
                CommTimeout             optional
 
        SAMTAC configuration, status and alarm parameters:
                InfoSCNL                required
                SOH_int                 optional

2. ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description.

command arg1

CommTimeout n

    Sets the communication timeout to n milliseconds. If unable to communicate with SAMTAC for n milliseconds, retry socket or terminate. Default: 5000 (milliseconds) 

ComPort n

    Sets the com port number to n. 

Debug n

    Sets the debug level: 0 or commented out for no debug logging; 1 - 4 for increasing verbosity. Default: no debug output. 

DeviceID n

    Sets DeviceID(serial) of the SAMTAC. This will be used to identify data coming from the SAMTAC and should match Sys values from SCNL. 

HeartbeatInt beat

    Beat the samtac2ew heart every beat seconds. 

InfoSCNL System Channel S C N L

    This command is used to define how samtac2ew maps a System and Channel Number to a Station Channel Name. It is also used as a channel selector as only those streams specified get passed on to the Earthworm Wave Ring. This forces the trace buf type to be of type TRACEBUF2. System is for the SAMTAC System ID name, Channel is for the SAMTAC channel number, S is for station name (5 chars), C is for channel identifier (3 chars), N is for network code (2 chars), and L is for location code (2 chars).

    #                Sys     Channel S       C       N   L
    InfoSCNL         21      1       ISTI    HHZ     CI  00
    InfoSCNL         21      2       ISTI    HHN     CI  00
    InfoSCNL         21      3       ISTI    HHE     CI  00

LogFile n

    If 0, don't output to logfile; if 1, do if 2, log to module log but not stderr/stdout 

ModuleId mod_id

    Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number. 

RingName ring	

    This is the ring into which the waveforms and messages are sent. 

SOH_int seconds	

    The interval in seconds between State of Health packets. Default in 300 seconds(5 minutes) 

Speed rate

    Connect to the SAMTAC-802U at the Speed rate specified. To use this input mode, the ComPort directive must also be used. The baud rates are the standard allowable rates : 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200. 

TcpAddr IPAddress

    Connect to the SAMTAC-802U at the ip address IPAddress. Note that the TcpPort is also required. 

TcpPort number

    Connect to the SAMTAC-802U at the ip address specified and this port number. Note that the TcpAddr is also required for this directive. TcpPort defaults to 5001 for the SAMTAC-802U. 

3. SAMPLE CONFIGURATION FILE

#
# samtac2ew configuration file
#
# This code receives serial data stream (SDS) packets from the SAMTAC via
# a TCP/IP port, converts them into Earthworm trace buf messages, and
# stuffs them into a wave ring.
#

TcpAddr         192.168.4.5     # IP address of SAMTAC interface
TcpPort         5001            # TCP port number of SAMTAC interface

# ComPort       1               # SAMTAC-802U COM port ID, 1=COM1, 2=COM, etc
# Speed         57600           # SAMTAC-802U baud rate

DeviceID        21              # SAMTAC DeviceID(serial), must be defined here for SCNL map

ModuleId        MOD_SAMTAC2EW   # module id for this import
RingName        WAVE_RING       # transport ring to use for input/output

LogFile         1               # If 0, don't output to logfile; if 1, do
                                # if 2, log to module log but not stderr/stdout

HeartbeatInt    30              # Heartbeat interval in seconds

# Optional commands:

SOH_int         300             # State Of Health packet interval in seconds. 
                                # Default is 5 minutes

CommTimeout     5000            # If unable to communicate with SAMTAC for X
                                # milliseconds, retry socket or terminate
                                # default: 5000 (milliseconds)

Debug           4               # debug level: 0 or commented out for no debug
                                # logging; 1 - 4 for increasing verbosity
                                # default: no debug output

#           Sys     Channel S       C       N   L
InfoSCNL    21      1       ISTI    HHA     ZZ  01
InfoSCNL    21      2       ISTI    HHB     ZZ  01
InfoSCNL    21      3       ISTI    HHC     ZZ  01
InfoSCNL    21      4       ISTI    HHD     ZZ  01
InfoSCNL    21      5       ISTI    HHE     ZZ  01
InfoSCNL    21      6       ISTI    HHF     ZZ  01
