Changes between Version 4 and Version 5 of srpar2ew


Ignore:
Timestamp:
04/08/12 18:11:53 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • srpar2ew

    v4 v5  
    5050 
    5151== Configuration File Commands == 
     52On startup, SrPar2Ew reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm SrPar2Ew module. In the control file, lines may begin with a valid SrPar2Ew command (listed below) or with one of 2 special characters: 
     53{{{ 
     54#  marks the line as a comment (example: # This is a comment). 
     55    
     56@  allows control files to be nested; one control file can be  
     57   accessed from another with the command "@" followed by  
     58   a string representing the path name of the next control file  
     59   (example: @model.d). 
     60}}} 
     61Command 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. 
     62 
     63=== Functional Command Listing === 
     64Below are the commands recognized by SrPar2Ew, 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. 
     65{{{ 
     66   Earthworm system setup: 
     67                ModuleId                required 
     68                RingName                required 
     69                LogFile                 required 
     70                HeartbeatInterval       required 
     71                OutputMsgType           optional 
     72                Debug                   optional 
     73 
     74   PARxCH data acquisition parameters: 
     75                AtodDriverName          required 
     76                AtodModelName           required 
     77                PortMode                required 
     78                SamplingRate            required 
     79 
     80   PARGPS timing module parameters: 
     81                GpsEnable               required 
     82                GpsDriverName           required 
     83                GpsSerialPort           required 
     84                GpsModelName            optional 
     85 
     86   Summary logging parameters: 
     87                SummaryInterval         optional 
     88                GpsReportInterval       optional 
     89                GpsBadLimit             optional 
     90 
     91   Channel SCNL parameters: 
     92                EwChannelScnl           optional 
     93                EwChannel               deprecated (use EwChannelScnl instead) 
     94 
     95   2nd board PARxCH data acquisition parameters: 
     96                AtodDriverNameN         optional 
     97                AtodModelNameN          optional 
     98                PortModeN               optional 
     99}}} 
     100 
     101 
     102=== Alphabetic Command Listing & Description === 
     103In 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. 
     104 
     105The following list is organized by: 
     106 
     107command [argument here] 
     108 
     109'''!AtodDriverName [driver_name]'''[[BR]] 
     110Function: PARxCH Configuration 
     111 
     112Sets the name of the PARxCH device driver to driver_name. This name is case sensitive and must match the name used when installing the driver. 
     113{{{ 
     114Default:  None 
     115Example:  AtodDriverName SrParXch0 
     116}}} 
     117 
     118'''!AtodDriverNameN [driver_name]'''[[BR]] 
     119Function: PARxCH 2 Board Configuration 
     120 
     121Sets the name of the second PARxCH device driver to driver_name. This name is case sensitive and must match the name used when installing the driver. This keyword is only used when running with two PAR8CH + one PARGPS. 
     122{{{ 
     123Default:  None 
     124Example:  AtodDriverNameN SrParXch1 
     125}}} 
     126 
     127'''!AtodModelName [xch_model_name]'''[[BR]] 
     128Function: PARxCH Configuration 
     129 
     130Indicates which member of the PARxCH family of 24 bit data acquisition devices is being used. xch_model_name can be PAR1CH, PAR4CH, or PAR8CH. This name is case sensitive and must match the model you are actually using. 
     131{{{ 
     132Default:  None 
     133Example:  AtodModelName PAR8CH 
     134}}} 
     135 
     136'''!AtodModelNameN [xch_model_name]'''[[BR]] 
     137Function: PARxCH 2 Board Configuration 
     138 
     139Indicates which member of the PARxCH family of 24 bit data acquisition devices is being used as the second A/D. Both xch_model_name and the argument for !AtodModelName must be PAR8CH to work correctly. This name is case sensitive and must match the model you are actually using. This keyword is only used when running with two PAR8CH + one PARGPS. 
     140{{{ 
     141Default:  None 
     142Example:  AtodModelNameN PAR8CH 
     143}}} 
     144 
     145'''Debug [n]''' 
     146Function: Earthworm setup 
     147 
     148Sets the log output level for !SrPar2Ew. 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. 
     149{{{ 
     150Default:  0 
     151Example:  Debug 1 
     152}}} 
     153 
     154'''!EwChannel [n sta comp net pin]'''[[BR]] 
     155Function: Channel Configuration 
     156 
     157This command is similar to !EwChannelScnl except there is no location value. Please use !EwChannelScnl instead. 
     158{{{ 
     159Default:  The channels are named CH## with component xxx and net SR 
     160          the pin number is set equal to the PARxCH channel number. 
     161Example:  EwChannel 0 CH00 xxx SR 0 
     162}}} 
     163 
     164'''!EwChannelScnl [n sta comp net loc pin]'''[[BR]] 
     165Function: Channel Configuration 
     166 
     167There should be one !EwChannelScnl command for each PARxCH channel, including special channels like the digital and GPS mark 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 PARxCH channel number while sta comp net loc pin give the earthworm SCNL and pin values. 
     168{{{ 
     169Default:  The channels are named CH## with component xxx, net SR and 
     170          location -- (indicating blank location).  The pin number is  
     171          set equal to the PARxCH channel number. 
     172Example:  EwChannelScnl 0 CH00 xxx SR -- 0 
     173}}} 
     174 
     175'''!GpsBadLimit [nbad]'''[[BR]] 
     176Summary Logging 
     177 
     178The 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. 
     179{{{ 
     180Default:  1 
     181Example:  GpsBadLimit 60 
     182}}} 
     183 
     184'''!GpsDriverName [driver_name]'''[[BR]] 
     185Function: PARGPS Configuration 
     186 
     187Sets the name of the PARGPS device driver to driver_name. This name is case sensitive and must match the name used when installing the driver. 
     188{{{ 
     189Default:  None 
     190Example:  GpsDriverName SrParGps0 
     191}}} 
     192 
     193'''!GpsEnable [on_off]'''[[BR]] 
     194Function: PARGPS Configuration 
     195 
     196This on_off switch is a case sensitive character string and must be either ON or OFF. It controls whether or not the PARGPS is used to provide precise time stamping of the data. If the PARGPS is not used, the waveform tracebuf times are determined by multiplying the sample rate by the number of samples. 
     197{{{ 
     198Default:  None 
     199Example:  GpsEnable ON 
     200}}} 
     201 
     202'''!GpsModelName [gps_model_name]'''[[BR]] 
     203Function: PARGPS Configuration 
     204 
     205Indicates what equipment is being used to determine GPS time. Currently, gps_model_name must be GARMIN, TRIMBLE, ONCORE, or PCTIME. TRIMBLE is the default and refers to the Symmetric Research Rev C GPS timing unit that includes a Trimble Ace III receiver. GARMIN refers to the Symmetric Research Rev D GPS timing unit that works with the Garmin GPS 18 LVC. 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. 
     206{{{ 
     207Default:  TRIMBLE 
     208Example:  GpsModelName GARMIN 
     209}}} 
     210 
     211'''!GpsReportInterval [nsec]'''[[BR]] 
     212Function: Summary Loggin 
     213 
     214A 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. 
     215{{{ 
     216Default:  0 
     217Example:  GpsReportInterval 1200 
     218}}} 
     219 
     220'''!GpsSerialPort [n]'''[[BR]] 
     221Function: PARGPS Configuration 
     222 
     223This integer selects which COM port is used to transfer the GPS serial NMEA strings that contain time and location to the PC. n must be 1 or 2 for serial port COM1 or COM2 respectively. 
     224{{{ 
     225Default:  None 
     226Example:  GpsSerialPort 1 
     227}}} 
     228 
     229'''!HeartbeatInterval [nsec]''' 
     230Function: Earthworm Setup 
     231 
     232Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by !SrPar2Ew. 
     233{{{ 
     234Default:  none 
     235Example:  HeartbeatInterval 60 
     236}}} 
     237 
     238'''!LogFile [n]'''[[BR]] 
     239Function: Earthworm Setup 
     240 
     241Sets 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, !SrPar2Ew 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). 
     242{{{ 
     243Default:  none 
     244Example:  LogFile 1 
     245}}} 
     246 
     247'''!ModuleId [mod_id]'''[[BR]] 
     248Function: Earthworm setup 
     249 
     250Sets 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 !SrPar2Ew. 
     251{{{ 
     252Default:  none 
     253Example:  MyModuleId MOD_SRPAR2EW 
     254}}} 
     255 
     256'''!OutputMsgType [trace_format]'''[[BR]] 
     257Function: Earthworm setup 
     258 
     259Tells !SrPar2Ew 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. 
     260{{{ 
     261Default:  TYPE_TRACEBUF2 (for v7.0 and greater, TYPE_TRACEBUF otherwise) 
     262Example:  OutputMsgType TYPE_TRACEBUF2 
     263}}} 
     264 
     265'''!PortMode [port_mode]'''[[BR]] 
     266Function: PARxCH Configuration 
     267 
     268Indicates which protocol is used to communicate over the PC parallel port. port_mode can be BPP, EPP, ECP/EPP, or ECP/BPP. This name is case sensitive and must match the mode your PC is actually using. Typically this setting is controlled in the BIOS CMOS setup area. Use the diagnostic program diag.exe that comes with the PARxCH to see which modes are enabled. 
     269{{{ 
     270Default:  None 
     271Example:  PortMode ECP/BPP 
     272}}} 
     273 
     274'''!PortModeN [port_mode]'''[[BR]] 
     275Function: PARxCH 2 Board Configuration 
     276 
     277Indicates which protocol is used to communicate over the second PC parallel port. port_mode can be BPP, EPP, ECP/EPP, or ECP/BPP. This name is case sensitive and must match the mode your PC is actually using. Typically this setting is controlled in the BIOS CMOS setup area. Use the diagnostic program diag.exe that comes with the PARxCH to see which modes are enabled. This keyword is only used when running with two PAR8CH + one PARGPS. 
     278{{{ 
     279Default:  None 
     280Example:  PortModeN ECP/BPP 
     281}}} 
     282 
     283'''!RingName [ring]'''[[BR]] 
     284Function: Earthworm setup 
     285 
     286Tells !SrPar2Ew 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. 
     287{{{ 
     288Default:  none 
     289Example:  RingName WAVE_RING 
     290}}} 
     291 
     292'''!SamplingRate [sps]'''[[BR]] 
     293Function: PARxCH Configuration 
     294 
     295Requests how many samples per second to acquire. The actual sampling rate may be a little different than the sps requested since only certain rates are achievable with the PARxCH hardware. Currently, the maximum allowed sps is 1000. 
     296{{{ 
     297Default:  None 
     298Example:  SamplingRate 100.0 
     299}}} 
     300 
     301'''!SummaryInterval [nsec]'''[[BR]] 
     302Function: Summary Logging 
     303 
     304A 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). The GPS information will be included only if you are using GPS (!GpsEnable ON). Set nsec to 0 if no summary lines are desired. 
     305{{{ 
     306Default:  0 
     307Example:  SummaryInterval 1200 
     308}}} 
     309 
     310 
     311=== Sample Configuration File === 
     312{{{ 
     313# FILE: srpar2ew.d                  Copyright (c), Symmetric Research, 2004-2010 
     314# 
     315# This is the SrPar2Ew parameter file for acquiring data with a  
     316# Symmetric Research PARxCH 24 bit A/D board and putting that 
     317# data onto an earthworm ring. 
     318# 
     319# The standard earthworm import_generic/export (or export_scnl) functions 
     320# can be used to transfer PARxCH tracebuf data from a local WAVE_RING to 
     321# a WAVE_RING on another machine.  If you have data from two different 
     322# PARxCH boards arriving at the same ring, you must ensure that each is 
     323# using a different ModuleId.  Otherwise, the two sets of data will  
     324# appear to be scrambled together which leads to lots of message sequence 
     325# number errors. 
     326# 
     327# If you wish to use MOD_SRPAR2EW for a ModuleId instead of 
     328# MOD_ADSEND_C, you must first define it in your earthworm.d file. 
     329# 
     330 
     331Debug               2               # control amount of info sent to log file 0-8 
     332                                    # warnings and errors always given 
     333                                    # 0 adds startup info 
     334                                    # 1 adds status summaries every GpsReportInterval 
     335                                    # 2 adds config + more detail (default) 
     336                                    # 3 adds trace data message info every second 
     337                                    # 4 adds counter values, NMEA strings every second 
     338                                    # Remaining levels 5-8 mostly for code debugging 
     339 
     340# 
     341# Basic Earthworm parameters: 
     342# 
     343 
     344MyModuleId         MOD_ADSEND_C     # module id for this instance of SrPar2Ew 
     345RingName           WAVE_RING        # shared memory ring for outputting acquired data 
     346LogFile            1                # 0 to turn off disk log file; 1 to turn it on 
     347HeartBeatInterval  60               # seconds between heartbeats, only checked 
     348                                    # after each second of data is acquired 
     349# 
     350# Optional Earthworm parameters: 
     351# 
     352 
     353OutputMsgType   TYPE_TRACEBUF2      # Older style waveforms were identified by 
     354                                    # Station/Channel/Network (SCN), the newer 
     355                                    # style also includes Location.  For Earthworm  
     356                                    # v7.0 and greater use, TYPE_TRACEBUF2.  If   
     357                                    # you need the older style, use TYPE_TRACEBUF. 
     358 
     359# 
     360# Basic PARxCH parameters: 
     361# 
     362 
     363AtodDriverName     SrParXch0        # name of PARxCH kernel mode device driver installed 
     364AtodModelName      PAR4CH           # which PARxCH is being used: PAR1CH, PAR4CH, PAR8CH 
     365PortMode           ECP/BPP          # protocol used for PC parallel port communications 
     366 
     367SamplingRate       100.0            # requested sampling rate - the actual rate may be 
     368                                    # slightly different from this due to hardware 
     369                                    # considerations 
     370 
     371# 
     372# Basic PARGPS parameters: 
     373# 
     374 
     375GpsEnable          ON               # ON if using PARGPS, OFF otherwise 
     376GpsDriverName      SrParGps0        # name of PARGPS kernel mode device driver installed 
     377GpsModelName       PARGPS           # usually PARGPS, may be PCTIME for NTP time 
     378GpsSerialPort      1                # COM port being used for serial NMEA messages 
     379 
     380 
     381# 
     382# Optional logging parameters: 
     383# 
     384SummaryInterval   1200              # seconds in log file between summary info 
     385                                    # use 0 for no reporting 
     386GpsReportInterval 3600              # seconds in log file between GPS lock lines 
     387                                    # use 0 for no reporting 
     388GpsBadLimit        300              # number of bad locks allowed per interval 
     389                                    # before error message is sent 
     390 
     391 
     392# 
     393# Channel info: SCNL AND PIN VALUES FOR EACH A/D CHANNEL 
     394# 
     395# EwChannelScnl lines relate the PARxCH channel numbers to the SCNL and pin 
     396# numbers used to identify channels in an earthworm system.  The pin 
     397# numbers are optional.  If a pin number is not specified for a channel,  
     398# the pin number is set to the A/D channel number. 
     399# 
     400# Three different versions of this section are given below showing how 
     401# the setup would look when using the PAR1CH, PAR4CH, or PAR8CH.  Only 
     402# the version corresponding to the PARxCH you are actually using should 
     403# be commented in, the other two should be commented out. 
     404# 
     405# The older keyword EwChannel is the same, except it has no location value. 
     406# If OutputMsgType = TYPE_TRACEBUF2 and EwChannel is used, the location field 
     407# defaults to "--" which means a blank location. 
     408# 
     409 
     410# 
     411# Sample EwChannelScnl section for the PAR1CH 
     412# 
     413 
     414#              A/D       
     415#            Channel   Sta   Comp  Net  Loc  Pin 
     416#            -------   ---   ----  ---  ---  --- 
     417#EwChannelScnl   0      CH00  xxx   SR   --    0 
     418#EwChannelScnl   1      MARK  xxx   SR   --    1   # Include this when using PARGPS 
     419 
     420 
     421 
     422# 
     423# Sample EwChannelScnl section for the PAR4CH 
     424# 
     425 
     426#              A/D       
     427#            Channel   Sta   Comp  Net  Loc  Pin 
     428#            -------   ---   ----  ---  ---  --- 
     429#EwChannelScnl   0      CH00  xxx   SR   --    0 
     430#EwChannelScnl   1      CH01  xxx   SR   --    1 
     431#EwChannelScnl   2      CH02  xxx   SR   --    2 
     432#EwChannelScnl   3      CH03  xxx   SR   --    3 
     433#EwChannelScnl   4      MARK  xxx   SR   --    4   # Include this when using PARGPS 
     434 
     435 
     436 
     437# 
     438# Sample EwChannelScnl section for the PAR8CH 
     439# 
     440 
     441#              A/D       
     442#            Channel   Sta   Comp  Net  Loc  Pin 
     443#            -------   ---   ----  ---  ---  --- 
     444#EwChannelScnl   0      CH00  xxx   SR   --    0 
     445#EwChannelScnl   1      CH01  xxx   SR   --    1 
     446#EwChannelScnl   2      CH02  xxx   SR   --    2 
     447#EwChannelScnl   3      CH03  xxx   SR   --    3 
     448#EwChannelScnl   4      CH04  xxx   SR   --    4 
     449#EwChannelScnl   5      CH05  xxx   SR   --    5 
     450#EwChannelScnl   6      CH06  xxx   SR   --    6 
     451#EwChannelScnl   7      CH07  xxx   SR   --    7 
     452#EwChannelScnl   8      DGTL  xxx   SR   --    8 
     453#EwChannelScnl   9      MARK  xxx   SR   --    9   # Include this when using PARGPS 
     454#EwChannelScnl  10      CNTR  xxx   SR   --   10   # Include this when using PARGPS 
     455 
     456 
     457 
     458# 
     459# Actual EwChannelScnl section being used ... 
     460# replace with appropriate values for your installation 
     461# 
     462 
     463#              A/D       
     464#            Channel   Sta   Comp  Net  Loc  Pin 
     465#            -------   ---   ----  ---  ---  --- 
     466EwChannelScnl   0      CH00  xxx   SR   --    0 
     467EwChannelScnl   1      CH01  xxx   SR   --    1 
     468EwChannelScnl   2      CH02  xxx   SR   --    2 
     469EwChannelScnl   3      CH03  xxx   SR   --    3 
     470EwChannelScnl   4      MARK  xxx   SR   --    4   # Include this when using PARGPS 
     471}}} 
     472 
    52473 
    53474== Helpful Hints == 
     
    55476 
    56477 
    57 The following list is organized by: 
    58  
    59 command [argument here]