NAME

q3302orb - acquire data from a Quanterra/Kinemetrics Q330 datalogger to an ORB

SYNOPSIS 

q3302orb [-pf pfname] [-calib_db dbname] [-dlclock dlname] [-v]
         targetname [orbtag1 orbname1 [orbtag2 orbname2 [...]]]

DESCRIPTION

q3302orb is a program for interacting with one or more Quanterra/Kinemetrics Q330 dataloggers. Data packets along with log messages, status messages, command responses and debug messages are written to a set of output ORBs. A large set of status channels can be generated as regular ORB waveform packets and, ultimately, archived as miniSEED files in the same manner as the seismic waveform data. Remote command and control of the dataloggers is accomplished through ORB-based command/response packet communications.

OPTIONS

ORB OUTPUT AND INPUT PACKETS

q3302orb 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. Although the dataloggers always put out one-second data packets, q3302orb can be configured to package waveform data into ORB packets of arbitrary time duration. q3302orb 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.

In addition to the seismic waveform data, q3302orb can also be configured to generate regularly sampled channels of status and state-of-health trace data that are either obtained directly from the dataloggers or are generated internally by q3302orb as it acquires data. These status waveform channels can be written out as regular ORB waveform packets and can be multiplexed arbitrarily with arbitrary time durations just like the real seismic waveforms.

q3302orb writes out a set of log messages as <target_name>/log packets, for log messages relating to the q3302orb instance and as <datalogger_name>/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).

q3302orb keeps a set of status information for each attached datalogger. All of this status information is written as a parameter file packet (with name <target_name>/pf/st) to the output orb at regular intervals. These status packets can be displayed by the program dlmon(1).

q3302orb reports configuration information when commanded. This configuration information is written as a parameter file packet (with name <datalogger_name>/pf/cf) to the output orb when requested.

q3302orb writes out certain debugging information as parameter file packets (with names <datalogger_name>/pf/fr and <datalogger_name/pf/frst) to the output orb at regular intervals when debugging is enabled.

Commands to q3302orb and to the attached dataloggers are all read by q3302orb from the command ORB with name <target_name>/pf/cm.

PROGRAM PARAMETER FILE

The q3302orb parameter file contains all of the information necessary for connecting to and acquiring data from the Q330 dataloggers. Following is an example q3302orb parameter file. 

#
#  This the q3302orb parameter file used to specify all of the settings needed to
#  communicate with a set of q330 dataloggers.
#

#  Following are global parameters:

pfstatusreport_interval		20		# This is the time interval in seconds for output
						#    status report packets
local_port_base			37500		# base port no. for local auto_fixed port assignments
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
config_orbtag			dataorb		# command line orb tag for configuration packets
qprot_orbtag			dataorb		# command line orb tag for qprot debug packets

packet_defs &Arr{			# ORB data packet definitions
	s1 &Arr{				# Standard one pchan-rate-second per packet
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		1			# no. of q330 one-second frames per data packet
		multiplexed	no			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode					# subcode fields in ORB srcname
	}
	s10 &Arr{				# 10 second single channel data packet
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		10			# no. of q330 one-second frames per data packet
		multiplexed	no			# Is this packet channel-wise multiplexed?
		suffix		GENC			# data type
		subcode					# subcode fields in ORB srcname
	}
	mst &Arr{				# full status multiplexing at 300 seconds
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		300			# no. of q330 one-second frames per data packet
		multiplexed	yes			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode		MST			# subcode fields in ORB srcname
	}
	mstc &Arr{				# full client status multiplexing at 300 seconds
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		300			# no. of q330 one-second frames per data packet
		multiplexed	yes			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode		MSTC			# subcode fields in ORB srcname
	}
	mf &Arr{				# full one-second multiplexing
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		1			# no. of q330 one-second frames per data packet
		multiplexed	yes			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode		MF			# subcode fields in ORB srcname
	}
	m1 &Arr{				# one sample-per-second pchan multiplexing in a 10 second packet
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		10			# no. of q330 one-second frames per data packet
		multiplexed	yes			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode		M1			# subcode fields in ORB srcname
	}
	m40 &Arr{				# 40 sample-per-second pchan multiplexing
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		1			# no. of q330 one-second frames per data packet
		multiplexed	yes			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode		M40			# subcode fields in ORB srcname
	}
	m100 &Arr{				# 100 sample-per-second pchan multiplexing
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		1			# no. of q330 one-second frames per data packet
		multiplexed	yes			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode		M100			# subcode fields in ORB srcname
	}
	m200 &Arr{				# 200 sample-per-second pchan multiplexing
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		1			# no. of q330 one-second frames per data packet
		multiplexed	yes			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode		M200			# subcode fields in ORB srcname
	}
	mbb &Arr{				# broadband channel multiplexing
		data_orbtag	dataorb			# command line orb tag for data packets
		twin		1			# no. of q330 one-second frames per data packet
		multiplexed	yes			# Is this packet channel-wise multiplexed?
		suffix		MGENC			# data type
		subcode		MBB			# subcode fields in ORB srcname
	}
}

#  Following are global default datalogger parameters:

statusrequest_interval		20		# This is the time interval in seconds for requesting
						#    datalogger status
statusreport_interval		20		# This is the time interval in seconds for reporting
						#    client status information as waveforms
datarate_interval		10.0		# This is the time interval in seconds for computing
						#    data rate averages
local_port_control		auto_fixed	# local port no. for control sockets
						#	"auto_fixed"	= automatically assign local port numbers
						#	an integer	= use integer as port number
local_port_data			auto_fixed	# local port no. for data sockets
timeout_control			5		# UDP read timeout in secs for control socket
timeout_data			20		# read timeout in secs for data
maxretries_control		5		# max no. of re-reads before re-connect for control socket
q330_port_base			5330		# base port no. for q330 logical port assignments
q330_authentication_code	0000000000000000 # default q330 authentication code
throttle			56000		# q330 communications throttle in bits-per-second
massrecenter_duration		5.0		# default time for pulsing sensor control lines
						#	for mass recenters

pchan_map &Arr{					# These map q330 physical channels to SEED net-sta-chan-loc codes
#	pchan	net_sta_chan[_loc]	calib	calper	segtype
	0	$DLNET_$DLSTA_HGZ_00	2338.08	-1.0	A
	1	$DLNET_$DLSTA_HGN_01	2338.08	-1.0	A
	2	$DLNET_$DLSTA_HGE_02	2338.08	-1.0	A
	3	$DLNET_$DLSTA_HHZ_03	$DB
	4	$DLNET_$DLSTA_HHN_04	$DB
	5	$DLNET_$DLSTA_HHE_05	$DB
}

rate_mask &Arr{					# These are mask values that modify the pchan_map SEED
#	stream	chanm	(locm)			#	chan-loc codes according to the q330
	0	L..	0.  			#	1 sps
	1	B..	1.			#	10 sps
	2	B..	2.			#	20 sps
	3	B..	3.			#	40 sps
	4	B..	4.			#	50 sps
	5	H..	5.			#	100 sps
	6	H..	6.			#	200 sps
	7	H..	7.			#	currently disabled
}

acq_matrix &Tbl{				# acquisition matrix
#	str0 str1 str2 str3 str4 str5 str6 str7
#	1    10   20   40   50   100  200
	s1   s1   0    0    s1   0    s1   0  # pchan 0
	s1   s1   0    0    s1   0    s1   0  # pchan 1
	s1   s1   0    0    s1   0    s1   0  # pchan 2
	s1   s1   0    0    s1   0    s1   0  # pchan 3
	s1   s1   0    0    s1   0    s1   0  # pchan 4
	s1   s1   0    0    s1   0    s1   0  # pchan 5
}

status_map &Arr{
#	parameter_name		pfst_nm	wf_nscl
	data_gps		gpss				# GPS status (reported as needed)
	data_gps_cs		gpsc				# reason for GPS cold-start (reported as needed)
	data_cnp_err_port	cnpp				# CNP error port number (reported as needed)
	data_cnp_err_code	cnpc				# CNP error code number (reported as needed)
	data_slavep_err_code	slpc				# slave processor error code number (reported as needed)
	data_dig_phase		dig				# digitizer phase change (reported as needed)
	data_dig_phase_why	digw				# reason for digitizer phase change (reported as needed)
	data_backup		bu				# saving daily configuration backup flag (reported as needed)
	data_record		rec				# recording window change (reported as needed)
	data_leap		leap				# leap second detected flag (reported as needed)
	data_pow_phase		powp				# power supply phase change (reported as needed)
	data_anl_fault		anlf				# analog fault (reported as needed)
	data_cal_error		cale				# calibration error (reported as needed)
	data_pll_drift		plld				# PLL drift over last 10 minutes (reported as needed)
	data_drift		drf				# time offset for phase out of range, Q330 will re-sync (reported as needed)
	data_sys_volt		dv	$DLNET_$DLSTA_QDV	# main system voltage (reported every 10 seconds)
	data_sys_temp		dt	$DLNET_$DLSTA_QDT	# main system temperature (reported every 10 seconds)
	data_sys_curr		da	$DLNET_$DLSTA_QDI	# main system current (reported every 10 seconds)
	data_ant_curr		aa	$DLNET_$DLSTA_QAI	# antenna current (reported every 10 seconds)
	data_spare_anl		sp	$DLNET_$DLSTA_QSP	# main system spare analog input (reported every 10 seconds)
	data_status_port	stp	$DLNET_$DLSTA_QPT	# main system status port value (configurable reporting interval)
	data_opto_input		opt	$DLNET_$DLSTA_QOP	# main system opto inputs (reported every 10 seconds)
	data_vco		vco	$DLNET_$DLSTA_QVC	# voltage controlled oscillator value (reported every 10 seconds)
	data_pkt_buf		pb	$DLNET_$DLSTA_QPB	# percentage packet buffer full (reported every 10 seconds)
	data_clk_qual		gps	$DLNET_$DLSTA_QCQ	# clock (GPS) quality (reported every 1 second)
	data_clk_pll		clq	$DLNET_$DLSTA_QPL	# clock phase lock loop status (reported every 1 second)
	data_clk_ltc		clt	$DLNET_$DLSTA_QCL	# time since GPS lock was lost (reported every 1 second)
	data_m0			m0	$DLNET_$DLSTA_QM0	# mass position for channel 0 (reported every 10 seconds)
	data_m1			m1	$DLNET_$DLSTA_QM1	# mass position for channel 1 (reported every 10 seconds)
	data_m2			m2	$DLNET_$DLSTA_QM2	# mass position for channel 2 (reported every 10 seconds)
	data_m3			m3	$DLNET_$DLSTA_QM3	# mass position for channel 3 (reported every 10 seconds)
	data_m4			m4	$DLNET_$DLSTA_QM4	# mass position for channel 4 (reported every 10 seconds)
	data_m5			m5	$DLNET_$DLSTA_QM5	# mass position for channel 5 (reported every 10 seconds)
	data_seis0_temp		s0t	$DLNET_$DLSTA_QST_00	# temperature for seismometer 0 (reported every 10 seconds)
	data_seis1_temp		s1t	$DLNET_$DLSTA_QST_01	# temperature for seismometer 1 (reported every 10 seconds)
	data_cal_abort		cala				# calibration abort occurred flag (reported as needed)
	data_cal_status		cals				# calibration status (reported as needed)
	data_suppl_pos		spv	$DLNET_$DLSTA_QPV	# analog unregulated positive supply voltage (reported every 10 seconds)
	data_suppl_neg		spn	$DLNET_$DLSTA_QNV	# analog unregulated negative supply voltage (currently not implemented)
	data_batt_temp		bt	$DLNET_$DLSTA_QBT	# battery temperature (configurable reporting interval)
	data_batt_cap		bc	$DLNET_$DLSTA_QBC	# battery capacity (configurable reporting interval)
	data_batt_dd		bd	$DLNET_$DLSTA_QBD	# battery depth of discharge (configurable reporting interval)
	data_batt_chg		bg	$DLNET_$DLSTA_QBG	# battery charging phase change (configurable reporting interval)
	data_batt_volt		bv	$DLNET_$DLSTA_QBV	# battery voltage (configurable reporting interval)
	data_bati_volt		iv	$DLNET_$DLSTA_QIV	# battery input voltage (configurable reporting interval)
	data_batt_curr		ba	$DLNET_$DLSTA_QBI	# battery current (configurable reporting interval)

	q330_drate_tot		dr	$DLNET_$DLSTA_QDR	# current total input+output data rate - bits per second
	q330_throttle		thr	$DLNET_$DLSTA_QTH	# current throttle setting - bits per second
	q330_comm_eff		ce	$DLNET_$DLSTA_QEF	# overall communications efficiency - percent
	q330_data_gaps		dg	$DLNET_$DLSTA_QDG	# data gaps - second
	q330_run_time		rtm	$DLNET_$DLSTA_QRT	# current run time - second
	q330_data_ltc		dlt	$DLNET_$DLSTA_QDL	# current data latency - second
	q330_pkts_proc		pkp	$DLNET_$DLSTA_QPK	# total number of packets processed
	q330_pkts_badsz		pkse	$DLNET_$DLSTA_QPS	# total number of packets with wrong sizes
	q330_pkts_chksm		pkce	$DLNET_$DLSTA_QPC	# total number of packets with checksum errors
	q330_byts_rd		byrd	$DLNET_$DLSTA_QBR	# total number of bytes read
	q330_byts_wr		bywr	$DLNET_$DLSTA_QBW	# total number of bytes written
}

status_disposition &Arr{
#	parameter_name		in_log?	in_pf?	wf_pktdef
	data_gps		yes	yes	0
	data_gps_cs		yes	no	0
	data_cnp_err_port	yes	no	0
	data_cnp_err_code	yes	no	0
	data_slavep_err_code	yes	no	0
	data_dig_phase		yes	no	0
	data_dig_phase_why	yes	no	0
	data_backup		yes	no	0
	data_record		yes	no	0
	data_leap		yes	no	0
	data_pow_phase		yes	no	0
	data_anl_fault		yes	no	0
	data_cal_error		yes	no	0
	data_pll_drift		yes	no	0
	data_drift		yes	no	0
	data_sys_volt		no	yes	mst
	data_sys_temp		no	yes	mst
	data_sys_curr		no	yes	mst
	data_ant_curr		no	yes	mst
	data_spare_anl		no	no	0
	data_status_port	no	no	0
	data_opto_input		no	no	0
	data_vco		yes	yes	mst
	data_pkt_buf		yes	yes	mst
	data_clk_qual		yes	yes	mst
	data_clk_pll		yes	yes	mst
	data_clk_ltc		yes	yes	mst
	data_m0			no	yes	mst
	data_m1			no	yes	mst
	data_m2			no	yes	mst
	data_m3			no	yes	mst
	data_m4			no	yes	mst
	data_m5			no	yes	mst
	data_seis0_temp		no	no	0
	data_seis1_temp		no	no	0
	data_cal_abort		yes	no	0
	data_cal_status		yes	no	0
	data_suppl_pos		no	no	0
	data_suppl_neg		no	no	0
	data_batt_temp		no	no	0
	data_batt_cap		yes	no	0
	data_batt_dd		yes	no	0
	data_batt_chg		yes	no	0
	data_batt_volt		no	no	0
	data_bati_volt		no	no	0
	data_batt_curr		no	no	0

	q330_drate_tot		no	yes	mstc
	q330_throttle		no	yes	mstc
	q330_comm_eff		no	yes	mstc
	q330_data_gaps		no	yes	mstc
	q330_run_time		no	yes	mstc
	q330_data_ltc		no	yes	mstc
	q330_pkts_proc		no	yes	0
	q330_pkts_badsz		yes	yes	0
	q330_pkts_chksm		yes	yes	0
	q330_byts_rd		no	yes	mstc
	q330_byts_wr		no	yes	mstc
}

debug_data			0		# Put out data debugging log messages?
debug_control			0		# Put out control debugging log messages?
debug_qprot			0		# Put out Quanterra protocol debugging ORB packets?
debug_udp			0		# Put out udp read/write log messages?

#  Following are datalogger parameter templates:

datalogger_templates &Arr{
	br6c &Arr{		# template for 6-channel units at BRTT
				#	nothing specified means to use global parameters
		acq_matrix &Tbl{				# acquisition matrix
		#	str0 str1 str2 str3 str4 str5 str6 str7
		#	1    10   20   40   50   100  200
	   		0    0    0    0    0    0    m200 0  # pchan 0
	   		0    0    0    0    0    0    m200 0  # pchan 1
	   		0    0    0    0    0    0    m200 0  # pchan 2
	   		s1   0    0    mbb  0    mbb  0    0  # pchan 3
	   		s1   0    0    mbb  0    mbb  0    0  # pchan 4
	   		s1   0    0    mbb  0    mbb  0    0  # pchan 5
		}
	}
	usarray	&Arr{	# template for USArray stations using VSAT links
		throttle        25600           # q330 communications throttle in bits-per-second
                timeout_control 20              # Timeout for reading control packets
                timeout_data    40              # Timeout for reading data packets
		log_minimum_resend_timeout 1.0  # Q330 link minimum resend timeout
		log_maximum_resend_timeout 16.0 # Q330 link maximum resend timeout
		log_group_timeout	18.0	# Q330 link group timeout
		log_group_count		32	# Q330 link group window size
		log_window_size		64	# Q330 link window size
		log_mtu			576	# Q330 link MTU size
		log_acknowledge_timeout	4.0	# Q330 link acknowledge timeout
		log_acknowledge_count	25	# Q330 link acknowledge window size
		pchan_map &Arr{			# These map q330 physical channels to SEED net-sta-chan-loc codes
		#	pchan	net_sta_chan[_loc]	calib	calper	segtype
			0	$DLNET_$DLSTA_HHZ	  $DB
			1	$DLNET_$DLSTA_HHN	  $DB
			2	$DLNET_$DLSTA_HHE	  $DB
			3	$DLNET_$DLSTA_HGZ	  $DB
			4	$DLNET_$DLSTA_HGN	  $DB
			5	$DLNET_$DLSTA_HGE	  $DB
		}
		acq_matrix &Tbl{		# acquisition matrix
		#	str0 str1 str2 str3 str4 str5 str6 str7
		#	1    10   20   40   50   100  200
	   		m1   0    0    m40  0    0    0    0  # pchan 0
	   		m1   0    0    m40  0    0    0    0  # pchan 1
	   		m1   0    0    m40  0    0    0    0  # pchan 2
	   		0    0    0    0    0    0    0    0  # pchan 3
	   		0    0    0    0    0    0    0    0  # pchan 4
	   		0    0    0    0    0    0    0    0  # pchan 5
		}
	}
	az3c &Arr{		# template for 3-channel units at UCSD
		pchan_map &Arr{			# These map q330 physical channels to SEED net-sta-chan-loc codes
		#	pchan	net_sta_chan[_loc]	calib	calper	segtype
			0	$DLNET_$DLSTA_HHZ_00	$DB
			1	$DLNET_$DLSTA_HHN_01	$DB
			2	$DLNET_$DLSTA_HHE_02	$DB
		}
		acq_matrix &Tbl{		# acquisition matrix
		#	str0 str1 str2 str3 str4 str5 str6 str7
		#	1    10   20   40   50   100  200
	   		m1   0    0    m40  0    m100 0    0  # pchan 0
	   		m1   0    0    m40  0    m100 0    0  # pchan 1
	   		m1   0    0    m40  0    m100 0    0  # pchan 2
	   		0    0    0    0    0    0    0    0  # pchan 3
	   		0    0    0    0    0    0    0    0  # pchan 4
	   		0    0    0    0    0    0    0    0  # pchan 5
		}
	}
}

#  Following is a list of dataloggers:

dataloggers &Tbl{
#	dlname		dlnet	dlsta	q330_serial_number	q330_ipaddress	qport	templ	disposition
 	BR_BQ330	BR	BQ330	010000069A40064D	q330		4	br6c	startacq
 	AZ_FLV2		AZ	FLV2	010000069A596EA0	198.202.124.196	4	az3c	startacq
	TA_Y22C		TA	Y22C	010000021BDCE892	123.45.67.186   3	usarray startacq

}

# Note: disposition is as follows:
#	"nothread"	= Don't start thread for this datalogger
#	"startthr"	= Start thread for this datalogger, but don't start acquisition
#	"startacq"	= Start thread and acquisition for this datalogger

#   Following are individual datalogger overrides:

BR_BQ330 &Arr{		# associative array with dlname as key
	local_port_control		37498	# local port no. for control sockets
	local_port_data			37499	# local port no. for data sockets
	throttle			512000	# q330 communications throttle in bits-per-second
}

The first part of the parameter file consists of a set of default values that will be used by all dataloggers and also a set of datalogger packet format and template definitions that are used to define which channels are acquired and how the individual SEED channels are written to the output ORB packets. The second part of the parameter file consists of a single dataloggers table that defines each of the individual Q330s for acquisition. The third part of the parameter file lists individual datalogger parameters that override the parameters specified in the previous two sections.

Parameters from the default section of the parameter file are as follows:

These default parameters define an acquisition "template" which we assign the token default. The default template can be used for any and all of the dataloggers if desired. Other acquisition templates can be defined through the datalogger_templates associative array (see below). This provides a convenient mechanism for defining a set of "default" configurations. For example, this becomes useful in situations where both three-channel and six-channel Q330 units are being acquired from the same instance of q3302orb.

Once all of the default parameters and the datalogger templates have been defined, it is relatively easy to set up acquisition from a particular set of Q330 dataloggers. This is done in the dataloggers table which is defined below:

Finally, any of the parameters can be overridden for particular dataloggers. This is done by specifying associative arrays whose names are set to the dlname fields in the dataloggers array. The contents of these associative arrays can contain any of the global default parameters which causes the values for those parameters to be overridden only for the specific datalogger.

BUGS AND CAVEATS

For those running the Antelope 4.4 pre-release version of q3302orb, the MGENC packet format is not enabled (this format is not understood by the 4.4 version of libPkt). Therefore, for the 4.4 version, multiplexing is not allowed.

SEE ALSO

dlmon(1)

AUTHOR

Danny Harvey
Boulder Real Time Technologies, Inc.

Table of Contents
Antelope Release 4.6 Linux 2.4.19-4GB 2004-07-01
Boulder Real Time Technologies, Inc For more information, contact support@brtt.com