EVN OM---FS Contribution Ari Mujunen, Ari.Mujunen@hut.fi v1.0, 19 August 1996 (This document contains a few main section headings besides "4. FS", since I would like to refer to them and I want to make sure that the referred number stays correct.) 1. SCHEDULING 2. PRE-SESSION SETUP/TEST 3. GPS TIMING 4. FIELD SYSTEM 4.1. Introduction The Field System (FS) acts as the controller for VLBI data acquisition hardware. The current version of FS, FS 9.1.5, runs on a Linux PC and it connects to hardware via MAT and/or MCB serial bus(es). The FS can be used to alter hardware settings and monitor hardware status by using SNAP commands. SNAP is a line-based command language which gives access to low-level hardware features of a Mark III, VLBA, or Mark IV data acquisition rack. Individual SNAP commands can be entered interactively, they can be grouped into named SNAP procedures (in '.prc' procedure files), and they can be put in time-controlled sequences in schedule '.snp' files. All SNAP command responses are shown in FS start-up window and also logged in a '.log' file. The most common way to use the FS for VLBI observations is to run '.snp' schedule files as described in section ``''. A typical FS usage session would consist of the following: o Logging in as 'oper', FS operator. o Starting the FS in main 'xterm' window with the command: ______________________________________________________________________ fs ______________________________________________________________________ o Entering SNAP commands in the 'oprin' operator input window. The commands and their responses will be echoed back in main 'ddout' window. Typical commands: ______________________________________________________________________ schedule=vt002,#1 -- start /usr2/sched/vt002.snp at line #1 help=schedule -- get a help window describing 'schedule' command form -- get status report of formatter terminate -- stop the FS ______________________________________________________________________ Arguments to SNAP commands follow a leading equals sign and multiple parameters are separated by commas. If you need to set up the FS for the first time, please read the section ``'' first, before continuing with the following sections which assume that the FS computer has already been set up. To stay updated with the latest development news about the FS, please make sure that at least somebody at your institute is subscribing the 'pcfs@bootes.gsfc.nasa.gov' FS mailing list. (Send a free-form request to join to 'pcfs-request@bootes.gsfc.nasa.gov'.) This is not a high-volume mailing list, but information posted here is not sent to any other VLBI-related mailing list and thus all FS users should be receiving it. If you have questions about, suggestions for, or problems with the FS you can contact 'Ari.Mujunen@hut.fi' and/or Ed Himwich at 'weh@vega.gsfc.nasa.gov'. 4.2. Organization of FS documentation An elaborate set of documents exists for FS9---they currently span three volumes. (If you do not have the set of documentation binders, please contact Nancy Vandenberg at 'nrv@bootes.gsfc.nasa.gov'.) Volume 1 is intended to support VLBI observing operations while Volume 2 contains reference material about MAT and MCB protocols, FS internal architecture, and computer-related issues. Volume 3 is actually a supplement to volumes 1 and 2: it contains new computer-related material introduced when FS was upgraded from FS8 (VENIX) to FS9 (Linux). If your supplement binder still contains the manuals "Operators' Reference" and "Experiment Operations" (as they were shipped in this way) may we suggest that you move these to their original location in Volume 1 and discard the old FS8 versions of these manuals. The following main categories of information are present in Volume 1: 1. Setting up. o A description of data acquisition rack setup can be found in either "Mark III" or "VLBA Hardware Setup", depending on your rack type. Most of Mark III instructions apply to Mark IV equally well. o "System Setup and Tests". o "Basic Checklists" manual supplements the pre-session setup/test notes of section ``''. o If there is any doubt about the performance of the narrow-track head positioner, use the instructions in the "Narrow Track Calibration" manual to calibrate it. o Setting up the FS software is described mainly in "Control Files" manual. These files, located at '/usr2/control', are used to configure the FS to match the hardware present. o "Standard Procedures" basically lists the contents of the station default SNAP procedure file '/usr2/proc/station.prc'. It may be useful when checking the applicability of the default procedures as a step of initial setup (see section ``''). 2. Running experiments. Information in these manuals will be needed continuously during sessions to operate the FS successfully. o "Operators' Reference" describes how to manage the user interface of the FS: windows, menus, command line entry. It also describes how to log in and out and how to start and stop the FS computer. o "Experiment Operations" shows how to use the FS and the most common SNAP commands to run schedules. It also describes strategies to handle exceptional situations during experiments: restarting schedules and/or the FS, telescope problems, tape drive problems. Section 4.5 of this manual is highly recommended and it is best read well in advance, since when a disaster happens, you will not have time to browse the manuals. o "SNAP Language" and "SNAP Commands" together describe what can be done with SNAP interactively, in procedures, and in schedule files. The commands are listed alphabetically in "SNAP Commands", so one has to familiarize oneself to the keywords to make it possible to find the correct one when needed. o At least the following sections of the "Utility Programs" manual describe programs regularly needed during sessions: o drudg: to convert '.skd'/'.drg' or '.vex' schedules into station- specific '.snp'/'.prc' files. o fmset: to set/check the VLBA or Mark IV formatter clock. o setcl: to set/check the FS computer clock. o pfmed: to modify '.prc' procedure files, especially while the FS is running. o Other programs are used less frequently: 'rwand' for Timex bar code reader, 'logex' for extracting reports from log files, and 'pcalr' to detect phase cal tones using the Mark III data buffer. o "Error Messages" may be useful when looking up an error message text when only the pair of a two-letter code and an error number is known. You may alternatively want to look up the error text in the file '/usr2/fs/control/fserr.ctl'. 3. Other manuals. o "Schedule File Format" defines the '.skd'/'.drg' format for Mark III schedules, used by 'sked' (geodesy scheduling program), 'PC SCHED' (DOS-based astronomy scheduling program), and 'drudg' (the '.skd'-to-'.snp' converter program of FS). o "Phase Cal System" and "Calibration Data" briefly describe phase cal, cable length, and meteorological measurements, mostly focusing on geodesy calibration. Volume 2 (and the supplementary third volume) contain the following: 1. FS computer and Linux-related information. o "Computer Reference" contains computer configuration and software installation instructions. The hard disk directory structure is described in section 3.0. Most importantly, general computer system procedures such as taking backups are explained in section 5.0. Section 1.0 enumerates a few general Linux handbook references as well as full GSFC and JIVE contact information. o "Computer Reference Appendices" contains rarely used instructions such as setting hardware jumpers on FS PC expansion boards, installing FS from scratch, maintaining Linux and using its kernel. Some of the information is more geared towards an user running FS on top of his/her own Linux PC installation instead of using the recommended FS PC configurations. 2. Antenna performance (pointing, gain) manuals. o "ACP User Guide", "Programs", "Files", "Algorithms" describe a comprehensive set of programs that can take pointing and on-off data and fit the data to a pointing model. 3. FS internals. o "Internal Architecture" explains the overall structure of FS, what each process/program does, and also the special interprocess communication features used. o "Station Programs" shows how to create station-specific software, especially antenna communications ('antcn') o "SNAP Command Subroutines" introduces a few most important subroutines one should use if one is implementing a new SNAP command in station-specific 'stqkr' program. o "Field System Programs" documents 'ddout', the program which formats log lines for start-up window display, and 'mcbcn', MCB serial bus communications used in VLBA racks. This contains MCB RS422 pinouts and documentation of the (now obsolete) "MCB Protocol Converter". o "Field System Common/Shared Memory" describes the variables shared by all FORTRAN/C programs of the system. 4.3. Checking the FS setup before a session After you have performed the first-time setup steps described in section ``'', it is still useful to check the following a few days before a session: 1. Control files (see section ``'') are up-to-date and that they match the antenna and receiver you are using. It is possible that you may have to change the following control files even during a given session: antenna.ctl: if your site has multiple antennas with different diameters, slew speeds, axis types, and limits. Antenna position is not defined here but in 'location.ctl'. dev.ctl: hardly ever needs to change except when you need to move MAT or MCB cables from one RS232 port to another. equip.ctl: lists receiver RF frequency, rack type, and tape drive parameters. VLBA racks can change from 'vlba' to 'vlbag' (MkIII compatible sampler wiring/connectors) and receiver RF frequency changes when changing receivers, but other parameters should stay relatively unchanged. location.ctl: defines site mane and code and antenna location. May change if your site has multiple antennas. time.ctl: the rate parameter may need updating if the FS PC clock lags or gains significantly. Please see section ``''. 2. Rack wiring (correct receiver, phase cal injected unless schedule prohibits it, IF inputs, IF patching, VLBA sampler cables, cables from formatter to tape drive) is correct for the schedules. If you need to move VLBA sampler cables from 'MkIII' to 'VLBA' position, please remember to 'sy=fmset' the formatter time, update '/usr2/control/equip.ctl' to reflect the change (racktype 'vlba' or 'vlbag' for MkIII position), and restart the FS. 3. Formatter time is correctly set and FS time model is accurate enough (see section ``''). 4. You can communicate with all devices in your rack. Use 'vread' (MkIII/IV) or 'bread' (VLBA) to read all video converters, 'tape' (and additionally 'rec' for VLBA) to read tape drive, and 'form' to read formatter status. 5. You can communicate with your antenna and any other site-dependent hardware you may have. You may want to check pointing by running 'fivpt' on a strong source as described in "ACP User's Manual". 6. You have transferred all the schedules of this particular session and you have converted them to '.snp'/'.prc' files and checked them. 'drudg' manual describes these steps, also section 2.0 of "Experiment Operations" shows how to convert schedules and get bar code labels for tapes. 7. You have enough prepassed tapes for the session. To prepass tapes you can use the SNAP command 'schedule=prepass,#1'. The default schedule 'prepass.snp' calls the station default SNAP procedure 'prepass' and after it unloads the tape. Invoking the schedule instead of just the SNAP procedure has the added benefit that all prepass runs will be logged into '/usr2/log/prepass.log'. If you use the 'label=xxxxxxxx,xxxx' command instead of 'cont' after threading in the tape, you will automatically get a permanent record of which tapes you have prepassed and when. 4.4. Running experiments Running schedules is described in "Experiment Operations" manual section 4.0. Section 4.5 lists typical problems during schedules and describes corrective actions. 4.5. Setting up for the first time Setting up the FS PC and Linux is covered in "Computer Reference" manual and additional information can be found in "Computer Reference Appendices". Each version of FS comes with its own setup notes, for example a file 'fs91up.txt' which outlines the differences of setting this particular version of FS when compared to the general instructions presented in sections 4.5 and 4.6 of "Computer Reference". 4.5.1. Control files The following files at directory '/usr2/control' set the characteristics of a FS installation: antenna.ctl: antenna diameter, slew speeds, axis type, and limits. ctlpo.ctl: controls antenna calibration programs (ACP), lists useful pointing sources. dev.ctl: assigns MAT, MCB, antenna, and GPIB Linux device names. equip.ctl: tape drive characteristics, receiver RF frequency, data acquisition rack type, recorder type, etc. head.ctl: narrow track head positioner calibration, LVDT voltage to head position scaling factors, inchworm motor speeds. Can be calibrated using instructions in "Narrow Track Calibration" manual. ibad.ctl: GPIB addresses of two-character GPIB device mnemonics. Mainly used for cable delay counter unit 'CA'. location.ctl: defines station name and one-letter code and antenna coordinates. matad.ctl: address assignments of MAT devices, device mnemonics (two characters) to hexadecimal addresses. mcbad.ctl: address assignments of MCB devices, two-character device mnemonics to two-character hexadecimal identifier. Identifiers are dynamically assigned and downloaded at FS startup time by the procedure 'vlbainit', called from automatic 'initi'. Whenever a given MCB module is powered off/on, the address information must be downloaded again with a corresponding 'bbc01=addr', 'rec=addr', or 'form=addr' SNAP command. mdlpo.ctl: pointing model coefficients are kept here. parpo.ctl: control file for 'xtrac' pointing measurement post-processing program. rxdef.ctl: defines the 32 A/D converted monitoring voltage channels of NASA S/X CDP receiver. rxdiode.ctl: defines the temperature sense diode characteristic voltage-to- kelvins curve. skedf.ctl: defines defaults to 'drudg', for example bar code label printer type. stcmd.ctl: enumerates station-specific SNAP commands. stpgm.ctl: enumerates site-specific field system programs that should be automatically started at 'fs' startup, except 'antcn' antenna communications. tedef.ctl: definitions for interfacing a spectrum analyzer via GPIB to FS. time.ctl: keeps FS PC clock characteristic drift rate (seconds/day), please see below section ``''. Please see "Control Files" manual for a detailed description of contents of control files. 4.5.2. Measuring the FS PC clock drift rate When the FS is started, the standard 'initi' SNAP procedure which is automatically run at every startup runs the program 'setcl' to synchronize FS PC time to formatter time. 'setcl' does not actually change time in FS PC, it merely measures the offset between PC and formatter clocks. Whenever the FS needs the current UT time, the FS PC clock is corrected with the measured offset plus a rate estimate. For FS time to be accurate, this rate estimate must accurately describe how many seconds a day the PC clock lags or gains. 'setcl' can be used to measure clock drift rate using the command 'sy=run setcl rate'. For this to work correctly you need to: 1. Make sure your formatter is set to correct UT time. 2. Make sure the FS PC internal clock is roughly correct. 3. After booting up the FS PC start 'fs' at least once and let 'setcl' (called as part of 'initi') establish a clock offset. 4. Leave FS PC running for at least 24 hours. 5. After this measure the rate with 'sy=run setcl rate'. You will get a new file '/usr2/control.time.new' which holds the new (seconds/day) rate estimate. Move this file over old 'time.ctl' and restart the FS to use the new rate. Please see the 'setcl' manual in "Utility Programs" section of Volume 1 of FS documentation for futher information of the FS clock model.