• Antelope Release 5.5 Linux 2.6.32-220.el6.x86_64 2015-04-21

 

# % nroff -man manpage.1 | more

NAME

change_q330_annc - change or review the annc structure on a q330 datalogger

SYNOPSIS

change_q330_annc 
	[-a authcode]
	[-d dlevent_db]
	[-l logdir]
	[-p pf]
	[-P port]
	[-s select]
	[-r reject]
	[-t targetname]
	[-v]
	[-V]
	[-n ]
	[-x exclude_dlsta]
	{-i dlevent_db | staq330_db}

SUPPORT


Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.

FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.

DESCRIPTION

Background

The Earthscope USArray Transportable Array (TA) network uses POC initiated operations to connect to the deployed q330 dataloggers. This requires the field crews to deploy the q330s with the ANNC structure properly setup to send these Point-of-Contact (POC) messages and to send them to host IPs that are ready to acquire them with a running pocd(1) processes. On occassion, the datalogger setup, or modifications using Willard go awry and the ANNC structure is set improperly, or the toggle to send out the POCs is not checked. This script is a way for a data center to query and/or modify that ANNC structure and is a wrapper around the q330util(1) command to request or set that structure. It is a sharp tool, and serious care/caution should be taken before you use this on all of your remote dataloggers!! Please run this in test/non-commanding mode with the -n option before unleashing it on your remote dataloggers!!

Auxilliary tables

This script has been developed for use at the ANF where we have implemented various table extensions to the css3.0 schema to help with the tracking of operational details. In particular, the default, non -i
run of the script requires that a staq330 table exist. If you do not have a staq330 table, you will need to run the script in interactive mode - a slow process if you have a multitude of dataloggers to check/modify. The staq330 table is created by the q330_baler(1) script. If you run in interactive mode, you can bypass the need for both a staq330 or q330comm table.

OPTIONS

See the EXAMPLE section for examples on how the different options should be selected depending on your task. You must select either the -i (interactive) mode, or specify a database which has a staq330 table.

FILES

There are three schema extension tables that can accessed by this script: staq330, q330comm, and dlevent. See the documentation available via dbhelp(1) for the css3.0 schema. See q330_baler(1) for information on populating the staq330 table. See q330coms(1) for how the q330comm table is created. See logs2dlevent(1) or dlreport(1) for how the dlevent table is used.

Four output files are created that contain information about the before/after POC settings (report.txt), a record of the actual q330util setannc commands that are sent (setannccmds.txt), a more detailed record of settings (settings.txt), and a shorter list of problem stations (tobefixed.txt). These files are written to the change_q330_annc_logs directory or your chosen directory if you use the -l logdir option, with a timestamp to show what date/time the change was attempted.

Examples of these four files are shown:

report.txt

   TA_I51A(Initial)  132.239.99.99 (?)   5  169.228.99.99 (host1)   5  128.95.999.99 (faraway1)  10  24.97.99.999 (monitor)  10
   TA_I51A(  Final)  169.228.88.88 (mylocal1)   5  128.95.88.888  (faraway2)  10  169.228.88.882 (mylocal2)   5  128.95.77.777 (faraway2)  10  24.97.99.999 (monitor)  10

setannccmds.txt

# TA_I51A
q330util -auth 00000000DEADBEEF sannc 74.198.9.99,0100000B64343434,5,0xa00,169.228.88.88,192.168.33.1,0,5,0xa1,2254,128.95.88.888,192.168.33.1,0,10,0xa1,2254,169.228.88.882,192.168.33.1,0,5,0xa1,2254,128.95.77.777,192.168.33.1,0,10,0xa1,2254,24.97.99.999,192.168.33.1,0,10,0xa1,2254

settings.txt

POC settings for TA_I51A (0) annc structure:
   IP address is: 132.239.99.99 (?)
   Router address is: 192.168.33.1 (?)
   Timeout is: 0
   Resume time is: 5
   Flags: 0xa1
   UDP port is: 2254

tobefixed.txt

Incorrect POC ip (132.239.99.99) in use for TA_I51A (0) annc structure
Incorrect POC ip (128.95.999.99) in use for TA_I51A (2) annc structure
Could not reach TA_I57A after attempting all alternate authorization code(s)

ENVIRONMENT

Need to have sourced $ANTELOPE/setup.csh and environment variable $PFPATH set.

PARAMETER FILE

The first portion of the parameter file describes the number of POC receivers, authentication codes to try, and some global settings. The core portion of the parameter file is the newannc structure with named sections for your POC receivers and their individual POC settings.
  • number_of_active_entries
    This number indicates how many hosts should be sent POCs from the datalogger. This number must match the number of setups defined in the newannc section of the parameter file.
  • default_authcode
    If your network uses a single authorization code for q330 access, specify it here.
  • alt_auth_codes
    If your network uses a variety of possible authorization codes, add them all here. The script will cycle through each one if it cannot access the datalogger with the default_authcode.
  • port_base
    The base port number for q330 communications. The default value is 5330 and is not normally changed unless particular/odd communication paths are needed. Override of the default can also be done with the -p port option which will take precedence.
  • unlock_flags
    This should likely always be set to 0xa00 if you are operating in POC mode. This sets the serial number unlocks.
  • flags
    This should likely always be set to 0xa1 as that is the value that indicates that POCs should be sent. Oft times when a datalogger is not sending POCs after a field visit, setting the annc structure to include this flag will start the POCs flowing.
  • dp_udp_port
    This should be set to 2254.
  • router_ip_addr
    This should likely be set to 192.168.33.1. Do not change it unless you know why it needs to be changed.
  • newannc
    This is an associative array containing named arrays which hold the settings for each of the POC receivers. The number of named arrays should match the number_of_active_entries specified earlier in the parameter file. The names used here do not have to match the nslookup names of the hosts that are receiving the POCs, but should each be unique.
  • newannc POC settings elements
    Each newannc structure has an associative array that must contain:
    
    dp_ip_addr	- IP to send POCs to (where a q330pocd process is run)
    router_ip_addr	- router IP address.  Almost always set to 192.168.33.1 for TA operations
    timeout_in_minutes	- set to 0 so the q330 will continue to send POCs "forever"
    resume_time_in_minutes	- delay in minutes without a registered connection before POCs are sent
    flags	-  should be set to 0xa1 to indicate POCs should be flowing
    dp_udp_port	- should likely always be set to 2254
    
    

EXAMPLE PARAMETER FILE

Below is the default change_q330_annc parameter file.


number_of_active_entries	5              # should match the number of defined setups in newannc
default_authcode        0000000000000007

unlock_flags            0xa00           # do not change this

alt_auth_codes  &Tbl{
        0000000000000000        	# this is the quanterra default and should always be included
        00000000DEADBEEF
        0000000000003333
#       000000000000BAAB
}

# default POC settings

flags                   0xa1
dp_udp_port             2254
router_ip_addr  192.168.33.1

exclude &Tbl{           # dataloggers to exclude from POC check and change
        TA_ABCD
}

newannc &Arr{		# named structures for settings for each POC receptor

anfacq &Arr{
dp_ip_addr      169.228.999.999
router_ip_addr  192.168.33.1
timeout_in_minutes      0
resume_time_in_minutes  5
flags                   0xa1
dp_udp_port             2254
}

anfdmcacq &Arr{
dp_ip_addr      128.95.999.999
router_ip_addr  192.168.33.1
timeout_in_minutes      0
resume_time_in_minutes  10
flags                   0xa1
dp_udp_port             2254
}

ceusnacq &Arr{
dp_ip_addr      169.228.999.888
router_ip_addr  192.168.33.1
timeout_in_minutes      0
resume_time_in_minutes  5
flags                   0xa1
dp_udp_port             2254
}

ceusndmcacq &Arr{
dp_ip_addr      128.95.999.888
router_ip_addr  192.168.33.1
timeout_in_minutes      0
resume_time_in_minutes  10
flags                   0xa1
dp_udp_port             2254
}

isti &Arr{
dp_ip_addr      24.97.987.654
router_ip_addr  192.168.33.1
timeout_in_minutes      0
resume_time_in_minutes  10
flags                   0xa1
dp_udp_port             2254
}

}

EXAMPLE

Interactive mode

  • Check the settings for single datalogger, interactively, using the staq330 table. Do not implement any changes to the settings.
    % change_q330_annc -n -i -d dbops/usarray
    : dl_sta to check: ('XX_ABCD'):  TA_109C
    : How is q330 sn provided? ('provide_pf|XXXXXXXXXXXXXXXX'):  pf/q3302orb_Strays.pf
    : How is IP provided? ('q330comm | path/to/q330logs/year/day/target/log | XXX.XXX.XXX.XXX'):  q330comm
    : Database with q330comm table? ('path/to/db/dbname'):  dbops/usarray
    Using ip from q330comm: 198.202.999.999
    
    No changes to POC setup needed for: TA_109C
    
    
  • Check, but do not change the settings for a single datalogger with no staq330 table available and looking for an IP from the q330logs available from the output of orb2logs.
    % change_q330_annc -n -i -d dbops/usarray
    : dl_sta to check: ('XX_ABCD'):  TA_109C
    : How is q330 sn provided? ('provide_pf|XXXXXXXXXXXXXXXX'):  0100000ABCABCABC
    : How is IP provided? ('q330comm | path/to/q330logs/year/day/target/log | XXX.XXX.XXX.XXX'):  q330logs/2015/051/tadataStrays/log
    Using ip from log: 198.202.999.999
    
    No changes to POC setup needed for: TA_109C
    
    

Report/Review

  • Check the settings for all dataloggers in a single targetname. Again, no changes made as the -n is used. The below example shows that TA_D55A has an incorrect setting, TA_D56A must have comms which are not functioning, and TA_D58A has the expected settings.
    % change_q330_annc -n -t tadataLow48 db/usarray
    Incorrect POC ip (132.239.999.999) in use for TA_D55A (0) annc structure
    Incorrect POC ip (128.95.999.999) in use for TA_D55A (2) annc structure
            User specified -n prevents setannc from running.
               annc structure remains as before for TA_D55A
    Could not reach TA_D56A after attempting all alternate authorization code(s)
    Station TA_D56A was unreachable.
    
    No changes to POC setup needed for: TA_D58A
    
    

Modify Settings

  • Correct the POC settings for a single station.
    % change_q330_annc -s "TA_D55A" db/usarray
    Incorrect POC ip (132.239.999.999) in use for TA_D55A (0) annc structure
    Incorrect POC ip (128.95.999.999) in use for TA_D55A (2) annc structure
    Changed POC config for TA_D55A
    
  • Correct the POC settings for a subset of stations, exclude one, use only stations from a single instance/targetname.
    % change_q330_annc -s "TA_[IJK].*" -x TA_I50A -t tadataLow48 db/usarray Incorrect POC ip (132.239.999.999) in use for TA_I51A (0) annc structure Incorrect POC ip (128.95.999.999) in use for TA_I51A (2) annc structure Could not reach TA_I57A after attempting all alternate authorization code(s) Station TA_I57A was unreachable. Incorrect POC ip (132.239.999.999) in use for TA_I58A (0) annc structure Incorrect POC ip (128.95.999.999) in use for TA_I58A (2) annc structure No changes to POC setup needed for: TA_I59A No changes to POC setup needed for: TA_I60A Could not reach TA_I61A after attempting all alternate authorization code(s) Station TA_I61A was unreachable.

DIAGNOSTICS

  • Could not reach XX_ABCD after attempting all alternate authorization code(s)
    Station was either off-line/no comms, or you are using the wrong authorization code when attempting to register.
  • No changes to POC setup needed for: XX_ABCD
    Station has POCs setup as specified in your parameter file.
  • Incorrect POC ip (XXX.XXX.XXX.XXX) in use for XX_ABCD (n) annc structure
    The numbered POC structure (n) has incorrect POC settings. This datalogger will receive a setannc q330util command to modify the POC structures. Note that only the numbered structures will be modified.

SEE ALSO

q3302orb(1)
q330util(1)
dlcmd(1)
q330_baler(1)

BUGS AND CAVEATS

Assumes same authorization code across all ports.

I expect log messages might be confusing if you have a single datalogger recording two stations worth of data (i.e. both XX_ABCD and XX_EFGH are collected via a single datalogger). Untested, so use caution.

Occassionally, the "Final" report of the annc structure is incomplete in the report.txt output file.

AUTHOR

Jennifer Eakins
Univ. of California, San Diego
Antelope User Group Contributed Software