Changes between Version 2 and Version 3 of srusb2ew


Ignore:
Timestamp:
04/08/12 19:50:03 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • srusb2ew

    v2 v3  
    4848 
    4949== Configuration File Commands == 
    50  
     50On startup, srusb2ew reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm srusb2ew module. In the control file, lines may begin with a valid srusb2ew command (listed below) or with one of 2 special characters: 
     51{{{ 
     52#  marks the line as a comment (example: # This is a comment). 
     53    
     54@  allows control files to be nested; one control file can be  
     55   accessed from another with the command "@" followed by  
     56   a string representing the path name of the next control file  
     57   (example: @model.d). 
     58}}} 
     59 
     60Command 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. 
     61 
     62=== Functional Command Listing === 
     63Below are the commands recognized by srusb2ew, 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. 
     64{{{ 
     65   Earthworm system setup: 
     66                ModuleId                required 
     67                RingName                required 
     68                LogFile                 required 
     69                HeartbeatInterval       required 
     70                OutputMsgType           optional 
     71                Debug                   optional 
     72 
     73   USBxCH data acquisition parameters: 
     74                AtodDriverName          required 
     75                AtodModelName           required 
     76                SamplingRate            required 
     77 
     78   USBxCH GPS timing parameters: 
     79                GpsModelName            required 
     80 
     81   Channel SCNL parameters: 
     82                EwChannelScnl           optional 
     83 
     84   Summary logging parameters: 
     85                SummaryInterval         optional 
     86                GpsReportInterval       optional 
     87                GpsBadLimit             optional 
     88 
     89   Debugging output parameters: 
     90                OutputPakFiles        optional 
     91                PacketsPerFile        optional 
     92}}} 
     93 
     94 
     95=== Alphabetical Command Listing & Description === 
     96In 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. 
     97 
     98The following list is organized by: 
     99 
     100command [argument here] 
     101 
     102'''!AtodDriverName [driver_name]'''[[BR]] 
     103Function: USBxCH Configuration 
     104 
     105Sets the name of the USBxCH device driver to driver_name. This name is case sensitive and must match the name used when installing the driver. 
     106{{{ 
     107Default:  None 
     108Example:  AtodDriverName SrUsbXch0 
     109}}} 
     110 
     111'''!AtodModelName [xch_model_name]'''[[BR]] 
     112Function: USBxCH Configuration 
     113 
     114Indicates which member of the USBxCH family of 24 bit data acquisition devices is being used. xch_model_name can be USB4CH, or USB8CH. This name is case sensitive and must match the model you are actually using. 
     115{{{ 
     116Default:  None 
     117Example:  AtodModelName USB4CH 
     118}}} 
     119 
     120'''Debug [n]'''[[BR]] 
     121Function: Earthworm setup 
     122 
     123Sets the log output level for srusb2ew. Errors and warnings are always logged. Level 0 adds startup info. Level 1 adds general summaries every !SummaryInterval seconds and GPS lock status summaries every !GpsReportInterval seconds. Level 2 adds some additional details. Level 3 adds time and satellite info for every 1 second buffer of data. Level 4 adds NMEA messages for every buffer. Level 5, primarily for code debugging, adds function calls and program variable values. 
     124{{{ 
     125Default:  0 
     126Example:  Debug 1 
     127}}} 
     128 
     129'''!EwChannelScnl [n sta comp net loc pin]'''[[BR]] 
     130Function: Channel Configuration 
     131 
     132There should be one !EwChannelScnl command for each USBxCH channel, including special channels like the digital and GPS PPS channels. This information is used to provide the full station, component, network and location names (SCNL) plus pin number as headers for the earthworm trace buffer messages. n indicates the USBxCH channel number while sta comp net loc pin give the earthworm SCNL and pin values. 
     133{{{ 
     134Default:  The channels are named CH## with component xxx, net SR and 
     135          location -- (indicating blank location).  The pin number is  
     136          set equal to the USBxCH channel number. 
     137Example:  EwChannelScnl 0 CH00 xxx SR -- 0 
     138}}} 
     139 
     140'''!GpsBadLimit [nbad]'''[[BR]] 
     141Function: Summary Logging 
     142 
     143The GPS lock status is determined once a second (ie for every buffer of data acquired). It is defined as good if 3 or more satellites are in view, and as bad otherwise. Since there are typically many seconds in one !GpsReportInterval, we need a criteria to determine if the GPS lock status summarized over the interval is good or bad. !GpsBadLimit provides this criteria. If the GPS lock status was bad for more than nbad seconds during the current !GpsReportInterval, the summary status is defined as bad. An error message is written to the Earthworm ring every time the summary GPS lock status changes. 
     144{{{ 
     145Default:  1 
     146Example:  GpsBadLimit 60 
     147}}} 
     148 
     149'''!GpsModelName [gps_model_name]'''[[BR]] 
     150Function: USBxCH Configuration 
     151 
     152Indicates what equipment is being used to determine GPS time. Currently, gps_model_name must be GARMIN, TRIMBLE, ONCORE, or PCTIME. GARMIN is the default and refers to a Garmin GPS 16x HVS receiver. TRIMBLE refers to the Trimble Ace III receiver (this model has been discontinued by Trimble). ONCORE refers to a Motorola Oncore GT+ unit (this model has been discontinued by Motorola). PCTIME means time stamping of the data is done using the PC system time and assumes this time is accurate because it has been set using NTP (Network Time Protocol) or some other GPS receiver. Other values may be allowed in the future. 
     153{{{ 
     154Default:  GARMIN 
     155Example:  GpsModelName GARMIN 
     156}}} 
     157 
     158'''!GpsReportInterval [nsec]'''[[BR]] 
     159Function: Summary Logging 
     160 
     161A summary of the GPS lock status is written to the log file every nsec seconds if the log file is turned on (!LogFile 1), a medium log output level is selected (Debug >= 1), and you are using GPS (!GpsEnable ON). Set nsec to 0 if no GPS lock status lines are desired. 
     162{{{ 
     163Default:  0 
     164Example:  GpsReportInterval 1200 
     165}}} 
     166 
     167'''!HeartbeatInterval [nsec]'''[[BR]] 
     168Function: Earthworm Setup 
     169 
     170Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by srusb2ew. 
     171{{{ 
     172Default:  none 
     173Example:  HeartbeatInterval 60 
     174}}} 
     175 
     176'''!LogFile [n]'''[[BR]] 
     177Function: Earthworm Setup 
     178 
     179Sets the on-off switch for writing a log file to disk. If n is 0, no log file will be written. If n is non-zero, srusb2ew will write daily log file(s) called nnnnn_yyyymmdd.log where nnnnn is the name of the configuration file (with the suffix '.d' removed) and yyyymmdd is the current UTC date (ex: 20040123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). 
     180{{{ 
     181Default:  none 
     182Example:  LogFile 1 
     183}}} 
     184 
     185'''!ModuleId [mod_id]'''[[BR]] 
     186Function: Earthworm setup 
     187 
     188Sets the module id for labeling all outgoing trigger, heartbeat, and error messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates to a unique single-byte number. In general, a different module ID is needed for each instance of srusb2ew. 
     189{{{ 
     190Default:  none 
     191Example:  MyModuleId MOD_SRUSB2EW 
     192}}} 
     193 
     194'''!OutputMsgType [trace_format]'''[[BR]] 
     195Function: Earthworm setup 
     196 
     197Tells srusb2ew whether to send waveform messages in the the old or new style tracebuf format. trace_format is a case sensitive character string and must be either TYPE_TRACEBUF or TYPE_TRACEBUF2. For Earthworm v7.0 and later, TYPE_TRACEBUF2 is the default. 
     198{{{ 
     199Default:  TYPE_TRACEBUF2 (for v7.0 and greater, TYPE_TRACEBUF otherwise) 
     200Example:  OutputMsgType TYPE_TRACEBUF2 
     201}}} 
     202 
     203'''!OutputPakFiles [n]'''[[BR]] 
     204Function: Debugging output 
     205 
     206Sets the on-off switch for writing native USBxCH acquired data packets to disk in SR .pak format files. If n is 0, no .pak files will be written. If n is 1, srusb2ew will write .pak files in addition to the normal EW tracebuf packets. The .pak files can be used for debugging or for alternate processing with SR utilities such as !Pak2Asc. A new sub-directory will be created in the current working directory. The name of the new directory is based on the acquisition start time and will be something like 2010-03-05-at-00-13-43. The .pak files will be written into this new directory. With names starting at 00000000.pak and increasing sequentially. The number of packets in each .pak file is controlled by the !PacketsPerFile parameter. 
     207{{{ 
     208Default:  0 
     209Example:  OutputPakFiles  
     210}}} 
     211 
     212'''!PacketsPerFile [n]'''[[BR]] 
     213Function: Debugging output 
     214 
     215Specifies the number of packets to include in each output .pak file. If the number given is less than the sampling rate/2 it will be increased. This parameter is ignored if .pak files were not requested by setting !OutputPakFiles to 1. 
     216{{{ 
     217Default:  none 
     218Example:  PacketsPerFile 650 
     219}}} 
     220 
     221'''!RingName [ring]'''[[BR]] 
     222Function: Earthworm setup 
     223 
     224Tells srusb2ew which shared memory region to use for output. ring is a character string (valid strings are listed in earthworm.d) that relates to a unique number for the key to the shared memory region. 
     225{{{ 
     226Default:  none 
     227Example:  RingName WAVE_RING 
     228}}} 
     229 
     230'''!SamplingRate [sps]'''[[BR]] 
     231Function: USBxCH Configuration 
     232 
     233Requests how many samples per second to acquire. The actual sampling rate may be a different than the sps requested since only certain rates are achievable with the USBxCH hardware. Allowed rates include 39.1, 65.1, 78.1, 130.2, 651.0. Currently, the maximum allowed sps is 651. 
     234{{{ 
     235Default:  None 
     236Example:  SamplingRate 130 
     237}}} 
     238 
     239'''!SummaryInterval [nsec]'''[[BR]] 
     240Function: Summary Logging 
     241 
     242A summary of the analog, GPS PPS, and GPS serial info read is written to the log file every nsec seconds if the log file is turned on (!LogFile 1) and a medium log output level is selected (Debug >= 1). Set nsec to 0 if no summary lines are desired. 
     243{{{ 
     244Default:  0 
     245Example:  SummaryInterval 1200 
     246}}} 
     247 
     248 
     249=== Sample Configuration File === 
     250{{{ 
     251# FILE: srusb2ew.d            Copyright (c), Symmetric Research, 2010 
     252# 
     253# This is the srusb2ew parameter file for acquiring data with a  
     254# Symmetric Research USBxCH 24 bit A/D board and putting that 
     255# data onto an earthworm ring. 
     256# 
     257# The standard earthworm import_generic/export (or export_scnl) functions 
     258# can be used to transfer USBxCH tracebuf data from a local WAVE_RING to 
     259# a WAVE_RING on another machine.  If you have data from two different 
     260# USBxCH boards arriving at the same ring, you must ensure that each is 
     261# using a different ModuleId.  Otherwise, the two sets of data will  
     262# appear to be scrambled together which leads to lots of message sequence 
     263# number errors. 
     264# 
     265# If you wish to use MOD_SRUSB2EW for a ModuleId instead of 
     266# MOD_ADSEND_C, you must first define it in your earthworm.d file. 
     267# 
     268 
     269Debug               2               # control amount of info sent to log file 0-8 
     270                                    # warnings and errors always given 
     271                                    # 0 adds startup info 
     272                                    # 1 adds status summaries every GpsReportInterval 
     273                                    # 2 adds config + more detail (default) 
     274                                    # 3 adds trace data message info every second 
     275                                    # 4 adds counter values, NMEA strings every second 
     276                                    # Remaining levels 5-8 mostly for code debugging 
     277 
     278OutputPakFiles      1               # output SR dat files in addition to the 
     279                                    # normal EW tracebuff packets, good for  
     280                                    # debugging or alternate processing with SR 
     281                                    # utilities such as Pak2Asc 
     282PacketsPerFile     650              # packets in each .PAK file, will be adjusted 
     283                                    # if less than sampling rate/2 
     284 
     285# 
     286# Basic Earthworm parameters: 
     287# 
     288 
     289MyModuleId         MOD_ADSEND_C     # module id for this instance of srusb2ew 
     290RingName           WAVE_RING        # shared memory ring for outputting acquired data 
     291LogFile            1                # 0 to turn off disk log file; 1 to turn it on 
     292HeartBeatInterval  60               # seconds between heartbeats, only checked 
     293                                    # after each second of data is acquired 
     294# 
     295# Optional Earthworm parameters: 
     296# 
     297 
     298OutputMsgType   TYPE_TRACEBUF2      # Older style waveforms were identified by 
     299                                    # Station/Channel/Network (SCN), the newer 
     300                                    # style also includes Location.  For Earthworm  
     301                                    # v7.0 and greater use, TYPE_TRACEBUF2.  If   
     302                                    # you need the older style, use TYPE_TRACEBUF. 
     303 
     304# 
     305# Basic USBxCH parameters: 
     306# 
     307 
     308AtodDriverName     SrUsbXch0        # name of USBxCH kernel mode device driver installed 
     309AtodModelName      USB4CH           # which USBxCH is being used: USB4CH, USB8CH 
     310 
     311SamplingRate       130.1            # requested sampling rate - the actual rate may be 
     312                                    # different from this due to hardware considerations 
     313                                    # currently only  78, 130, or 650 is allowed. 
     314 
     315# 
     316# Basic USBxCH GPS parameters: 
     317# 
     318 
     319GpsModelName       GARMIN           # usually GARMIN or TRIMBLE, may be PCTIME for NTP time 
     320 
     321 
     322# 
     323# Optional logging parameters: 
     324# 
     325SummaryInterval   1200              # seconds in log file between summary info 
     326                                    # use 0 for no reporting 
     327GpsReportInterval 3600              # seconds in log file between GPS lock lines 
     328                                    # use 0 for no reporting 
     329GpsBadLimit        300              # number of bad locks allowed per interval 
     330                                    # before error message is sent 
     331 
     332 
     333# 
     334# Channel info: SCNL AND PIN VALUES FOR EACH A/D CHANNEL 
     335# 
     336# EwChannelScnl lines relate the USBxCH channel numbers to the SCNL and pin 
     337# numbers used to identify channels in an earthworm system.  The pin 
     338# numbers are optional.  If a pin number is not specified for a channel,  
     339# the pin number is set to the A/D channel number. 
     340# 
     341# Three different versions of this section are given below showing how 
     342# the setup would look when using the USB4CH or USB8CH.  Only the 
     343# version corresponding to the USBxCH you are actually using should 
     344# be commented in, the other two should be commented out. 
     345# 
     346# The older keyword EwChannel is the same, except it has no location value. 
     347# If OutputMsgType = TYPE_TRACEBUF2 and EwChannel is used, the location field 
     348# defaults to "--" which means a blank location. 
     349# 
     350 
     351# 
     352# Sample EwChannelScnl section for the USB4CH 
     353# 
     354 
     355#              A/D       
     356#            Channel   Sta   Comp  Net  Loc  Pin 
     357#            -------   ---   ----  ---  ---  --- 
     358#EwChannelScnl   0      CH00  xxx   SR   --    0 
     359#EwChannelScnl   1      CH01  xxx   SR   --    1 
     360#EwChannelScnl   2      CH02  xxx   SR   --    2 
     361#EwChannelScnl   3      CH03  xxx   SR   --    3 
     362#EwChannelScnl   4      DGTL  xxx   SR   --    4 
     363#EwChannelScnl   5      PPS   xxx   SR   --    5 
     364#EwChannelScnl   6      CNTR  xxx   SR   --    6 
     365 
     366 
     367 
     368# 
     369# Sample EwChannelScnl section for the USB8CH 
     370# 
     371 
     372#              A/D       
     373#            Channel   Sta   Comp  Net  Loc  Pin 
     374#            -------   ---   ----  ---  ---  --- 
     375#EwChannelScnl   0      CH00  xxx   SR   --    0 
     376#EwChannelScnl   1      CH01  xxx   SR   --    1 
     377#EwChannelScnl   2      CH02  xxx   SR   --    2 
     378#EwChannelScnl   3      CH03  xxx   SR   --    3 
     379#EwChannelScnl   4      CH04  xxx   SR   --    4 
     380#EwChannelScnl   5      CH05  xxx   SR   --    5 
     381#EwChannelScnl   6      CH06  xxx   SR   --    6 
     382#EwChannelScnl   7      CH07  xxx   SR   --    7 
     383#EwChannelScnl   8      DGTL  xxx   SR   --    8 
     384#EwChannelScnl   9      PPS   xxx   SR   --    9 
     385#EwChannelScnl  10      CNTR  xxx   SR   --   10 
     386 
     387 
     388 
     389# 
     390# Actual EwChannelScnl section being used ... 
     391# replace with appropriate values for your installation 
     392# 
     393 
     394#              A/D       
     395#            Channel   Sta   Comp  Net  Loc  Pin 
     396#            -------   ---   ----  ---  ---  --- 
     397EwChannelScnl   0      CH00  SHZ   SR   U4    0 
     398EwChannelScnl   1      CH01  SHZ   SR   U4    1 
     399EwChannelScnl   2      CH02  SHZ   SR   U4    2 
     400EwChannelScnl   3      CH03  SHZ   SR   U4    3 
     401EwChannelScnl   4      DGTL  DIG   SR   U4    4 
     402EwChannelScnl   5      PPS   GPS   SR   U4    5 
     403}}} 
     404 
     405  
    51406== Helpful Hints == 
    52407 
    53408 
    54409 
    55 The following list is organized by: 
    56  
    57 command [argument here]