wiki:srpar2ew

Version 8 (modified by branden, 8 years ago) (diff)

--

Earthworm Module: srpar2ew

Contributed by:

Function

Symmetric Research Digitzer module for parallel port digitizers, formerly known as srparxchewsend.

Details

Introduction

!SrPar2Ew allows the Symmetric Research PARxCH family of low cost 24 bit data acquisition systems to send data to an Earthworm system running either Windows (Win2K, WinXP) or Linux. PARxCH models with 1, 4, and 8 channels are all supported. It can also support 16 channels if run with 2 PAR8CH on the same PC which share one PARGPS. Very accurate timestamping of the acquired data results when the optional PARGPS timing unit is used with the PARxCH A/D. Timestamping using the PC system time set by NTP is also available.

!SrPar2Ew reads configuration information like sampling rate and PARxCH model from an Earthworm style .d configuration file and then opens drivers and initializes hardware for the PARxCH and optional PARGPS. Then it starts the A/D and goes into an infinite loop acquiring data, converting it to Earthworm tracebuf (or tracebuf2) format and writing it out to the specified Earthworm ring. On each pass through the loop, it also sends a heartbeat message to the Earthworm ring.

In order to run !SrPar2Ew, you need a working Earthworm system, a PARxCH A/D board, and the PARxCH device driver and library software that comes with the board and is also available free from the Symmetric Research website www.symres.com. For accurate timing information, a PARGPS timing unit and its software is also required.

Setup

Follow any instructions given in the official documentation to get Earthworm up and running.

The first step in adding PARxCH data is to install the PARxCH with GPS software. This can be done by unpacking the pxgpsw2k.zip or pxgpslnx.tar file and running the included install script to copy the SR software to the \sr\parxch and \sr\pargps directories. Linux users should substitute /usr/local/sr/parxch for references to the \sr\parxch directory.

You will also need to install the PARxCH and PARGPS device drivers using the indriver utilities from their respective driver subdirectories. See the readme files in the \sr\parxch\driver and \sr\pargps\driver directories for more information.

Then hook up the A/D hardware. Make sure it is working correctly by running the diagnostic program in the \sr\parxch\diags directory. The acquisition programs in the \sr\parxch\scope and \sr\parxch\simple directories can also help in checking out a new system.

To add the PARGPS (optional but recommended), first install the PARGPS device driver using the indriver utility provided in the PARGPS software. See the readme file in the \sr\pargps\driver directory for more information. Then hook up the PARGPS hardware. Make sure it is working correctly by running the diagnostic program in the \sr\pargps\diags directory.

Once Earthworm and the PARxCH/PARGPS are working on their own, it's time to get them working together. Edit the srpar2ew.d configuration file settings so they are appropriate for your system.

At this time, you will probably also want to edit some additional Earthworm module configuration files to handle the PARxCH data that will be coming. This might include adding tanks for the PARxCH data in wave_serverV.d if the data is to be saved on the same computer or setting the PARxCH channels in export_scn.d if the data is to be exported to another computer.

In the beginning, it is probably best to use two separate command prompt windows. In the first, run startstop to start Earthworm. In the second, type "srpar2ew srpar2ew.d" without the quotes to start the PARxCH acquiring and sending data.

You can check the log files and run diagnostic programs like sniffring to help diagnose any problems. If something isn't going right, it is easy to stop !SrPar2Ew, modify its configuration file, and restart it without having to stop the rest of Earthworm. Once you've got your parameters set right, then go ahead and have startstop control !SrPar2Ew too.

Compiling

!SrPar2Ew is written in C and is compiled and linked using the standard Earthworm makefiles such as makefile.nt. In order to successfully compile, access to the PARxCH and PARGPS system software is required. This software, including source, is included with every PARxCH and PARGPS purchase. It is also available for free download from the Symmetric Research website www.symres.com.

All Symmetric Research software, including the PARxCH system software and !SrPar2Ew, has been designed so a single set of source code can service different operating systems. This is accomplished primarily through the use of conditional compilation which selects OS specific code at compile time based on which SROS_xxx setting is defined. Valid options include SROS_WIN2K (for both Windows 2000 and XP) and SROS_LINUX. Solaris is not available.

Although using a PARGPS timing unit is optional, it is recommended. Even if you are not using the PARGPS, you should always install the PARGPS software and define GPS_AVAILABLE when compiling the PARxCH and !SrPar2Ew software, so the timing portions of the code are included.

More Info

General questions about Earthworm are probably best answered by the official Earthworm User's discussion group. But, if you have specific questions about !SrPar2Ew and its configuration parameters, please let us know at info@….

Configuration File Commands

On 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:

#  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: @model.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.

Functional Command Listing

Below 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.

   Earthworm system setup:
                ModuleId                required
                RingName                required
                LogFile                 required
                HeartbeatInterval       required
                OutputMsgType           optional
                Debug                   optional

   PARxCH data acquisition parameters:
                AtodDriverName          required
                AtodModelName           required
                PortMode                required
                SamplingRate            required

   PARGPS timing module parameters:
                GpsEnable               required
                GpsDriverName           required
                GpsSerialPort           required
                GpsModelName            optional

   Summary logging parameters:
                SummaryInterval         optional
                GpsReportInterval       optional
                GpsBadLimit             optional

   Channel SCNL parameters:
                EwChannelScnl           optional
                EwChannel               deprecated (use EwChannelScnl instead)

   2nd board PARxCH data acquisition parameters:
                AtodDriverNameN         optional
                AtodModelNameN          optional
                PortModeN               optional

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.

The following list is organized by:

command [argument here]

AtodDriverName [driver_name]
Function: PARxCH Configuration

Sets 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.

Default:  None
Example:  AtodDriverName SrParXch0

AtodDriverNameN [driver_name]
Function: PARxCH 2 Board Configuration

Sets 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.

Default:  None
Example:  AtodDriverNameN SrParXch1

AtodModelName [xch_model_name]
Function: PARxCH Configuration

Indicates 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.

Default:  None
Example:  AtodModelName PAR8CH

AtodModelNameN [xch_model_name]
Function: PARxCH 2 Board Configuration

Indicates 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.

Default:  None
Example:  AtodModelNameN PAR8CH

Debug [n]
Function: Earthworm setup

Sets 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.

Default:  0
Example:  Debug 1

EwChannel [n sta comp net pin]
Function: Channel Configuration

This command is similar to EwChannelScnl except there is no location value. Please use EwChannelScnl instead.

Default:  The channels are named CH## with component xxx and net SR
          the pin number is set equal to the PARxCH channel number.
Example:  EwChannel 0 CH00 xxx SR 0

EwChannelScnl [n sta comp net loc pin]
Function: Channel Configuration

There 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.

Default:  The channels are named CH## with component xxx, net SR and
          location -- (indicating blank location).  The pin number is 
          set equal to the PARxCH channel number.
Example:  EwChannelScnl 0 CH00 xxx SR -- 0

GpsBadLimit [nbad]
Summary Logging

The 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.

Default:  1
Example:  GpsBadLimit 60

GpsDriverName [driver_name]
Function: PARGPS Configuration

Sets 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.

Default:  None
Example:  GpsDriverName SrParGps0

GpsEnable [on_off]
Function: PARGPS Configuration

This 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.

Default:  None
Example:  GpsEnable ON

GpsModelName [gps_model_name]
Function: PARGPS Configuration

Indicates 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.

Default:  TRIMBLE
Example:  GpsModelName GARMIN

GpsReportInterval [nsec]
Function: Summary Loggin

A 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.

Default:  0
Example:  GpsReportInterval 1200

GpsSerialPort [n]
Function: PARGPS Configuration

This 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.

Default:  None
Example:  GpsSerialPort 1

HeartbeatInterval [nsec]
Function: Earthworm Setup

Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by !SrPar2Ew.

Default:  none
Example:  HeartbeatInterval 60

LogFile [n]
Function: Earthworm Setup

Sets 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).

Default:  none
Example:  LogFile 1

ModuleId [mod_id]
Function: Earthworm setup

Sets 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.

Default:  none
Example:  MyModuleId MOD_SRPAR2EW

OutputMsgType [trace_format]
Function: Earthworm setup

Tells !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.

Default:  TYPE_TRACEBUF2 (for v7.0 and greater, TYPE_TRACEBUF otherwise)
Example:  OutputMsgType TYPE_TRACEBUF2

PortMode? [port_mode]
Function: PARxCH Configuration

Indicates 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.

Default:  None
Example:  PortMode ECP/BPP

!PortModeN [port_mode]
Function: PARxCH 2 Board Configuration

Indicates 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.

Default:  None
Example:  PortModeN ECP/BPP

RingName [ring]
Function: Earthworm setup

Tells !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.

Default:  none
Example:  RingName WAVE_RING

SamplingRate [sps]
Function: PARxCH Configuration

Requests 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.

Default:  None
Example:  SamplingRate 100.0

SummaryInterval [nsec]
Function: Summary Logging

A 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.

Default:  0
Example:  SummaryInterval 1200

Sample Configuration File

# FILE: srpar2ew.d                  Copyright (c), Symmetric Research, 2004-2010
#
# This is the SrPar2Ew parameter file for acquiring data with a 
# Symmetric Research PARxCH 24 bit A/D board and putting that
# data onto an earthworm ring.
#
# The standard earthworm import_generic/export (or export_scnl) functions
# can be used to transfer PARxCH tracebuf data from a local WAVE_RING to
# a WAVE_RING on another machine.  If you have data from two different
# PARxCH boards arriving at the same ring, you must ensure that each is
# using a different ModuleId.  Otherwise, the two sets of data will 
# appear to be scrambled together which leads to lots of message sequence
# number errors.
#
# If you wish to use MOD_SRPAR2EW for a ModuleId instead of
# MOD_ADSEND_C, you must first define it in your earthworm.d file.
#

Debug               2               # control amount of info sent to log file 0-8
                                    # warnings and errors always given
                                    # 0 adds startup info
                                    # 1 adds status summaries every GpsReportInterval
                                    # 2 adds config + more detail (default)
                                    # 3 adds trace data message info every second
                                    # 4 adds counter values, NMEA strings every second
                                    # Remaining levels 5-8 mostly for code debugging

#
# Basic Earthworm parameters:
#

MyModuleId         MOD_ADSEND_C     # module id for this instance of SrPar2Ew
RingName           WAVE_RING        # shared memory ring for outputting acquired data
LogFile            1                # 0 to turn off disk log file; 1 to turn it on
HeartBeatInterval  60               # seconds between heartbeats, only checked
                                    # after each second of data is acquired
#
# Optional Earthworm parameters:
#

OutputMsgType   TYPE_TRACEBUF2      # Older style waveforms were identified by
                                    # Station/Channel/Network (SCN), the newer
                                    # style also includes Location.  For Earthworm 
                                    # v7.0 and greater use, TYPE_TRACEBUF2.  If  
                                    # you need the older style, use TYPE_TRACEBUF.

#
# Basic PARxCH parameters:
#

AtodDriverName     SrParXch0        # name of PARxCH kernel mode device driver installed
AtodModelName      PAR4CH           # which PARxCH is being used: PAR1CH, PAR4CH, PAR8CH
PortMode           ECP/BPP          # protocol used for PC parallel port communications

SamplingRate       100.0            # requested sampling rate - the actual rate may be
                                    # slightly different from this due to hardware
                                    # considerations

#
# Basic PARGPS parameters:
#

GpsEnable          ON               # ON if using PARGPS, OFF otherwise
GpsDriverName      SrParGps0        # name of PARGPS kernel mode device driver installed
GpsModelName       PARGPS           # usually PARGPS, may be PCTIME for NTP time
GpsSerialPort      1                # COM port being used for serial NMEA messages


#
# Optional logging parameters:
#
SummaryInterval   1200              # seconds in log file between summary info
                                    # use 0 for no reporting
GpsReportInterval 3600              # seconds in log file between GPS lock lines
                                    # use 0 for no reporting
GpsBadLimit        300              # number of bad locks allowed per interval
                                    # before error message is sent


#
# Channel info: SCNL AND PIN VALUES FOR EACH A/D CHANNEL
#
# EwChannelScnl lines relate the PARxCH channel numbers to the SCNL and pin
# numbers used to identify channels in an earthworm system.  The pin
# numbers are optional.  If a pin number is not specified for a channel, 
# the pin number is set to the A/D channel number.
#
# Three different versions of this section are given below showing how
# the setup would look when using the PAR1CH, PAR4CH, or PAR8CH.  Only
# the version corresponding to the PARxCH you are actually using should
# be commented in, the other two should be commented out.
#
# The older keyword EwChannel is the same, except it has no location value.
# If OutputMsgType = TYPE_TRACEBUF2 and EwChannel is used, the location field
# defaults to "--" which means a blank location.
#

#
# Sample EwChannelScnl section for the PAR1CH
#

#              A/D      
#            Channel   Sta   Comp  Net  Loc  Pin
#            -------   ---   ----  ---  ---  ---
#EwChannelScnl   0      CH00  xxx   SR   --    0
#EwChannelScnl   1      MARK  xxx   SR   --    1   # Include this when using PARGPS



#
# Sample EwChannelScnl section for the PAR4CH
#

#              A/D      
#            Channel   Sta   Comp  Net  Loc  Pin
#            -------   ---   ----  ---  ---  ---
#EwChannelScnl   0      CH00  xxx   SR   --    0
#EwChannelScnl   1      CH01  xxx   SR   --    1
#EwChannelScnl   2      CH02  xxx   SR   --    2
#EwChannelScnl   3      CH03  xxx   SR   --    3
#EwChannelScnl   4      MARK  xxx   SR   --    4   # Include this when using PARGPS



#
# Sample EwChannelScnl section for the PAR8CH
#

#              A/D      
#            Channel   Sta   Comp  Net  Loc  Pin
#            -------   ---   ----  ---  ---  ---
#EwChannelScnl   0      CH00  xxx   SR   --    0
#EwChannelScnl   1      CH01  xxx   SR   --    1
#EwChannelScnl   2      CH02  xxx   SR   --    2
#EwChannelScnl   3      CH03  xxx   SR   --    3
#EwChannelScnl   4      CH04  xxx   SR   --    4
#EwChannelScnl   5      CH05  xxx   SR   --    5
#EwChannelScnl   6      CH06  xxx   SR   --    6
#EwChannelScnl   7      CH07  xxx   SR   --    7
#EwChannelScnl   8      DGTL  xxx   SR   --    8
#EwChannelScnl   9      MARK  xxx   SR   --    9   # Include this when using PARGPS
#EwChannelScnl  10      CNTR  xxx   SR   --   10   # Include this when using PARGPS



#
# Actual EwChannelScnl section being used ...
# replace with appropriate values for your installation
#

#              A/D      
#            Channel   Sta   Comp  Net  Loc  Pin
#            -------   ---   ----  ---  ---  ---
EwChannelScnl   0      CH00  xxx   SR   --    0
EwChannelScnl   1      CH01  xxx   SR   --    1
EwChannelScnl   2      CH02  xxx   SR   --    2
EwChannelScnl   3      CH03  xxx   SR   --    3
EwChannelScnl   4      MARK  xxx   SR   --    4   # Include this when using PARGPS

Helpful Hints