The "original" 107" TCS Technical Manual

File contents

::::::::::::::
TCShelp_1.txt
::::::::::::::
2.7m TCS Software
Introduction

The 2.7m Telescope Control System (TCS) consists of 3 software components:
the graphical user interface, the monitor program, and the PMAC software.

The user (normally an observer or observatory staff personnel) usually
interacts with the graphical user interface program known as the TCS GUI.
The is an X Windows/Motif program that can be displayed on any X-capable
unix workstation, a PC/Mac having X served software, or an X terminal.
There will be at least LynxOS and Solaris executable versions of this program.
While this program can be executed and display telescope information from
anywhere, there are restrictions in the software to control what functions
are permissible from what locations.

The gui display comprises 5 distinct parts:
The menu area
The command button area
The alert (error) button area
The command status display area, and
The Display areas
These are described in other Help messages.

The LynxOS-based software which is the interface between the user interface
and the hardware is the TCS Monitor program. It is a multi-threaded POSIX-
compliant, real-time unix/c program that communicates with the telescope dome,
ICE, autoguiders, and graphical user interface via TCP sockets. The latter
feature eliminates the problems associated with serial RS-232 connections.
Handpaddles, and absolute encoders for HA, Dec, and focus are connected via
serial lines.

One can think of this program as a telescope daemon or a telescope resource
server. The host machine for this program is a 100 MHz Intel Pentium system
dubbed "colossus".

The last component in the software suite is the PMAC code. This interpreted
code and associated parameters are store on the control conputer's disk and
loaded into the Delta Tau PMAC (Programmable Motion Controller) when required.

Point Command Equivalents

Throughout this document, decending through menus will be shown by starting
with the menu title and then separating submenus with "->". Thus displaying
this message would be shown as Help->Introduction... .

p - Display point parameters
=> See main display

p a hh mm ss.s - dd mm ss.s [epoch [ra-pm [dec-pm]]]
- Airmass only
=> See main display. Shows airmass for current telescope position.

p b nnnn - Yale Bright Star nnnn
=> Next->Star->BSC and fill in number

p c - Give scope coordinates (same as 'p')
=> See main display

p h - A help message
=> Help->(any item you wish to see)

p i nnnn - IC object nnnn
=> Next->Extended Object->IC and fill in number

p k nnnn - FK5 star nnnn
=> Next->Star->FK5 and fill in number

p l - Point again to the last object
=> Next->Previous Object, click on an object and press apply.

p m nnnn - Messier object nnnn
=> Next->Extended Object->Messier and fill in number

p n nnnn - NGC object nnnn
=> Next->Extended Object->NGC and fill in number

p t [zd [mag]] - Find FK5 stars near zenith
=> Next->FK5 Stars Near Zenith, change search parameters and push "search"

p z - Re-zero point's coordinates
=> Zero->New HA/Dec Zero Points

p z d - Restore default zeros
=> Zero->Default HA/Dec Zero Points

p z r - Restore previous zeros
=> Zero->Previous HA/Dec Zero Points

p z 0 - Set P Zeros to zero
=> Zero->Set HA/Dec Zero Points to 0

p z x y - Set P Zeros to x asec RA and y asec Dec
=> Zero->Specify HA/Dec Zero Points Values and fill in values

p 'object' - Find 'object', e.g. 'p alpha hya', 'p castor', or 'p mars'.
=> Next->Star By Name->Common Name OR Letter+Constellation
or Next->Solar System->Planets->Mars

p nnnn - Object nnnn in worklist.dat\n");
=> Next->Worklist->(worklist name) and select from list.
(Will need to "Transfer/Load Worklist" before worklist will be in
list.)

p hh mm ss.s -dd mm ss.s [epoch [ra-pm [dec-pm]]]") - Point to RA and Dec
=> Next->Manual Entry->Ra/Dec and fill in values

::::::::::::::
TCShelp_2.txt
::::::::::::::
The TCS Graphical User Interface Menu Area

The Menu area includes 5 separate menus:
File,
Next,
Tools,
View, and
Special (available only from Colossus).

Note that there are menus (and pushbuttons) accessible from the status display
area. Those are discussed in the section pretaining to the status display.)

1) The File menu handles file input and output.
----

Open/Transfer Worklists...
Open/Transfer Ephemerides...
Open Macro Fil...
Open Command File...
Save Command History As...
Save Object History As...
Clear Lists
-------------------
Exit

Worklists are user supplied ASCII files in the format described in the Help
menu item on 'Files'. The selected worklist file is transferred to the
TCSMonitor and its name is added to the Next menu item Worklists. Up to
10 worklists at once can be controlled by the TCS. If an 11th file is
openned, its name replaces that of the 1st entry in the menu.

Ephemerides are generally used for minor planets and comets, with any
reasonable number of objects combined into one file as described in the
Help menu item on 'Files'. The selected ephemeris file is transferred to
the TCSMonitor and its name is added to the Next menu item Solar
System->Ephemerides, with object names being listed with each ephemeris
file name. Up to 20 worklists at once can be controlled by the TCS. If
a 21st file is openned, its name replaces that of the 1st entry in the
menu. The number of objects per ephemeris file is limited only by the
number of objects that will fit on the screen.

Command files are ascii files containing commands in the TCS command language.
(The command language syntax is described in the Help Menu item on 'Files'.)
The name of this file is then put into the �command file� section of the display
area of the gui. The commands can be accessed and executed via a pop-up window
activiated by the Tools->Previous or Manual Commands. Only one command can be
executed at a time. Only one command file is available at once.

Another type of command file is the macro file, which can also be read in here.
This file is accessed via the Tools->From Macro File popup. The difference
from a command file is that part or all of the macro file can be executed at once. The macro file can make use of more advanced language features like
"waittime" and "waitevent".

When a command is given by the TcsGui to the TcsMonitor, it is saved in the
View->Save Command History As... popup, and to a file $HOME/.tcsgui.cmd.
Likewise when one of these commands moves the telescope to the next object,
that command is saved in the View->Object History and Next->Previous Object
popups, as well as to the file $HOME/.tcsgui.obj. To save the contents of these
files, one can select the Save Command History As... and Save Object History
As... menu items, respectively.

The TcsGui keeps track of the files and object names associated with the
worklist and ephemeris lists that are openned. This allows the program to
put these names back in the menus when the program is restarted.
When one wants to start over with a different selection of files, (such as
at the beginning of new observing run), one can execute the Clear Lists
command.

N.B. If the TcsGui is run on the control computer (colossus), provision will
need to be made with the staff to transfer any the worklst, ephemeris, and
command files to the appropriate directory (normally "/data/observer") on the
controller.

2) The Next menu controls selection of the next object to prepare for tracking.
----
To slew to and track an object, it is first necessary to select it via an item
in the next menu (or by selecting the down arrow in the reference coordinate
in the status display area) to load it into the "next" area of the display and
then to push the "Go Next" button in the command button area (described in
the "buttons" section).

Star
FK5
BSC
Star By Name
Common Name
Letter + Constellation
FK5 Stars Near Zenith
Extended Objects
NGC
IC
Messier
Solar System
Planets
Mercury
Venus
Mars
Jupiter
Saturn
Uranus
Neptune
Pluto
Ephemerides
(Files as defined by user...)
(Objects as defined by user...)
Moon
Sun
Worklists
(Files as defined by user...)
Manual Entry
RA/Dec
HA/Dec
Az/El
Previous Object
------------------
Flat
Zenith
Stow
Standby

The intent of most of these items should be self-apparent. Where catalogs
are involved, the program provides a popup window to which the user can supply
a catalog number of the desired object. Selecting stars by name provides
scrolled lists from which the user can select a star.

Selecting "FK5 Stars Near Zenith" provides a pop-up window in which the
observer can select the maximum zenith distance and magnitude limits of stars
to be chosen. Pushing the "Search!" button creates the star list and the
sky plot based on these criteria. The star may be selected by clicking on the
skyplot, or on the scrolled list and Apply button. The skyplot also shows the
current obstruction map. Note that the skyplot is not automatically updated
to compensate for the earth's rotation, so the positions will grow stale.

As mentioned above, the ephemeris lists are populated by user-selected
ephemeris files. The user selects an ephemeris from the menu and the
appropriate object from the ephemeris' sub-menu. Using the worklist is just
as easy: with the selection of the user-defined worklist from the menu, a
window pops up with a scrolled list of all the object in the worklist and a
skyplot of all the objects and the current obstruction map. (Those objects
below the horizon are plotted on the horizon.) The object may be selected
from the list or from the plot.

"Previous Object" pops up a scrolled window with a list of the objects already
selected during this execution of the TcsGui program. One can select any of
these objects and press Apply to accept the selection as the next object or
OK to accept it and close the window.

Selecting Zenith, Stow, and Flat will load preconfigured positions for these
places in the sky. Standby stops telescope tracking.

3) Tools Menu provides various operational options.
-----

Handpaddle Rates...
-------------------
Weather Units
English (default)
Metric
Enable Dome Automation
Park Dome *
-------------------
Override Telescope Limits (Once)
-------------------
Previous or Manual Command
From Macro File *
From Command File *

The Handpaddle rate menu item pops up a window that allow the observer to
change the handpaddle slew, search, track, and guide rates (analog) and the
digital mode step size. Also the polarity of the handpaddle directions are
changed in this window, permitting the changing of dec direction over axis
or altering directions depending on whatever is most comfortable for the user.
The rate of movement between reference positions is governed by the last item
in the window.

Weather units are by default in English units. Changing this changes the labels
and values on the display of the pressure, temperature, dew point temperature,
and wind speed. It does not change the values in the weather history display
(which is a verbatim display of the weather monitor output).

Enabling dome automation permits the domeauto system to preposition the dome
to the commanded telescope position. Home Dome (which is grey-ed out and
insensitive until dome automation is enabled) moves the dome to its stow
position at about 90 degrees azimuth.

The "Override Telescope Limits" feature allow a user to get out of or
further into a restricted area of scope motion (e.g., near the north pier
or the south hand rails).

"Previous of Manual Commands" pops up a window containing a list of previously
executed commands. Any one of these can be selected by clicking. Another
option is to type in a known command in the text box. Clicking on Apply will
execute the command. OK will also execute the command but will then close
the window. See the response area to learn whether the command worked or not.

"From Macro File" is accessible only after a command file has been selected
via the File menu. This item will pop a window showing the macro command file.
Click on Run to execute the entire macro or click on a command and Run to
execute part of the file. Press Stop to halt execution and Resume to start
where it left off.

"From Command File" is accessible only after a command file has been selected
via the File menu. This item will pop a window showing the command file.
You may click on one of these commands at a time and push Apply (or OK) to
execute it.

4) View Menu shows various sets of information of potential interest to the
----
observer.

Sky Plot of Next
Point
Weather History
Command History (same as "Previous or Manual Command")
Object History (same as "Previous Object")

The "Sky Plot of Next" plots each successive object chosen from the Next menu.
This is cummulative with the latest selection having a cursor superimposed on
it. When this plot becomes overly crowded, you may hit the reset key to clear
it. The plot includes the current obstruction mask superimposed on the polar
plot of the sky.

"Point" is meant to approximate the output from the point command. There are
two parts to the window this command pops up. The top shows the mean, apparent,
refracted (observed) and flexed positions, based on the catalog position.
The second section shows the same info as based on the actual telescope
position (corrected for zero point offsets).

"Weather History" displays up to 500 most recent weather lines from the
weather file on atlas.

"Command History" is the same as "Previous or Manual Command", provided here
for completeness.

"Object History" of the same as "Previous Object", provided here for
completeness.

5) There is also a Special command menu meant only for mountain staff.
-------
This allows access to features like telescope mount modelling data acquisition.
It also permits turning off of the sun avoidance feature, which can interfere
with daytime maintenance.

::::::::::::::
TCShelp_3.txt
::::::::::::::
The TCS Graphical User Interface Button and Status Area

The button and status area consists of 3 distinct areas separated by lines:
Command Buttons,
Alarm (Error warning) Buttons, and
Command Status.

The buttons and status area are color coded for readability: Green for active,
status normal. Red or dark red indicate warning or danger, and blue or white
just to highlight an area.

1) Command Button Area

There are currently 4 buttons in the command button area:
Active
Go Next
Abort Move
Emergency Stop

The "Active" button is green when the the TcsMonitor is accepting commands
from the current copy of the TcsGui. Unless it is the first TcsGui to execute
after TcsMonitor starts, this button will be red. The program will still
display information, but commands will not be accepted. To rectify this, press
the Active button. Is should then turn green. If not, it is likely that you
are running or viewing this program from a system that is not permitted to
give the Monitor commands. (No, we don't want the telescope run from Munich!)

Moving the telescope to a new object is a 2-step process. First, an object
must be selected from the 'next' menu or the down buttons next to the
reference positions. Once the object's coordinates are loaded, the use can
push "Go Next" at his or her leisure. Assuming there are no limit violations
(e.g. trying to run into a guard rail) the telescope will slew to the
next object and, if appropriate, track on it. (The telescope will not track
once it has slewed to a Flat, Zenith, Stow, or manually-entered HA/Dec or
Az/El positions.)

If the slew has begun and you decide the object you picked was a Bad Idea,
push the "Abort Move" button to halt the slew (but not tracking motion).
If you have to really stop motion (kill the amps, throw on the brakes) to
keep from hitting your co-observer, for instance, push "Emergency Stop".
It is a BIG button. You can't miss it (unless covered by another window).
There are similarly labeled hardware buttons on the console and handpaddles
if you prefer the feel of a "real" button.

2) The Alert (Error) Button Area

Any abnormal condition is reported in the Alarm area. An example is the
"TCS Connect Error" which flashes when the TcsGui cannot find the TcsMonitor
to talk with. If the problem is that the monitor is not running, start it,
wait a few seconds and then push the error button to try to establish
communications. Most other error buttons are not wired to fix the problem
they report. Many of the significant errors (Cannot talk to the PMAC, Wind
Warning, etc.) flash. Others are static.

A list of the errors that can appear are:
TCS Connect Error
TCS Format Error (Wrong version of TcsGui for TcsMonitor in use -
or socket message length overflow.)
PMAC Servo Counter Halted
Can't open Mask file (Obstruction limits)
Can't open Weather file
Can't predict Pluto (Only if JPL ephemeris is not available.)
Can't open EOP file (Earth Orientation Parameters: UT1-UTC, x, and y)
EOP File Stale "
Can't open Environmental file
Can't open HA Absolute Encoder
Can't open Dec Absolute Encoder
Scope below Horizon
Scope in Soft Limits
Too close to Sun
Temperature
Humidity
Pressure
Dome not responding
Can't open Focus Absolute Encoder
Can't record to mount model file
High Humidity - check condensation
High Humidity - CLOSE DOME!
High Winds - Raise wind screens
High Winds - Work down wind
High Winds - Be prepared to close
High Winds - CLOSE DOME!
Reported Wind Speeds May Be Low
PMAC status
TCS caused Emergency Stop
PMAC caused Emergency Stop
PMAC Stopped Telescope
HA Tracking Inhibited
Dec Tracking Inhibited
Within 5 Degrees of Horizon
Scope in 5 Degree Limits
Scope in 1/2 Degree Limits

3) The Command Status Display Area

This is a scrolled list showing the responses to the last 5 commands given
by the TcsGui to the TcsMonitor. (These commands can be viewed explicitly by
selecting the View->Command History option.)

This area will indicate when there has been a problem with a user selection
or command (e.g., limit violation when you tell the scope to point to an
object below the horizon). This area can help build a sense of confidence
that everything is running properly.
::::::::::::::
TCShelp_4.txt
::::::::::::::
The TCS Graphical User Interface Display Area

The rest of the TCS Gui program's main window is dedicated to system status
display and more buttons and menus to change options. Most of the information
below is updated 5 times a second, or whenever it changes (to reduce flicker).

At the top left of the screen is the current date and UTC, Julian date, local
sidereal time, and local hour angle of the telescope. Below this is the
actual telescope position (corrected for 'flexure', i.e. mount model),
command position and the difference between these (Offset). The part of this
"offset" due to the autoguider or similar instrument is shown next. Units
for these quantities are all hours/minutes/seconds and degrees/minutes/seconds.

Note that the "telescope" fields flash when the telescope is in motion. These
telescope fields are displayed against a yellow background so they can be
quickly located, even from a distance.

Below this are the zeros (in arc seconds), which can be changed by pushing
the button containing the "Zero" label. This produces a with options
New HA/Dec Zero Points - Use the 'Offset' for the zeros (with
cos dec correction in HA)
Default HA/Dec Zero Points - Some default value. Usually 0.
Previous HA/Dec Zero Points - The last zeros used.
Set HA/Dec Zero Points to 0 - Should be obvious.
Specify Values for HA/Dec Zero Points...
- pops up a window into which to type
new values.

Note that the zeros are added to the TELESCOPE and not commanded positions.

The telescope tracking rates are shown next (in arcseconds) with a button
to press to change the rates and engage/disengage fixed rate tracking. Normally
these rates are calculated internally to the Monitor program based on
successive object positions which automatically compensate for differential
refraction, mount model, and object rates (for ephemerides).

The software has the flexibility to record and reuse reference positions.
Control of these occupy the next 3 lines of information. The reference positions
are recorded by selecting an option from those shown when the Ref 1 or Ref 2
button is pushed. One can select the telescope or commanded position for
reference 1, and telescope, commanded, or offset for reference 2. The offset
option pops up a window (the same as when pressing "Ref2-Ref1") to allow
entering the desired difference between reference 1 and reference 2. This
offset is always relative to reference position 1. The down arrows between
the HA and Dec reference positions loads that reference position as the
next object.

Note that the reference position is stored internally in the same way as the
original object, to maintain accuracy, consistency, and repeatability.
If the reference position is a catalog mean position, and the reference
position is taken from 'command' then the catalog mean position
is stored internally, despite the fact that an observed position may be
shown in the reference position field. Where this can get confusing is when
the reference position is loaded into 'next', where the original catalog
mean position is shown. If the 'telescope' position is chosen, the observed
position at current epoch is shown. When the position is moved from next to
command, the refraction is corrected for the natural motion of the object.
The commanded position no longer matches the reference position, even though
they are the same position internally. Confusion is the price for some
modicum of flexibility! Note that the speed of the motion between the
reference positions is governed by the "Reference Rate" field in the Tools->
Handpaddle Rates popup.

The sliders that appear below the reference position information shows the
current telescope velocity. The purpose is to verify telescope motion in
some obvious visual way that can be seen from a great distance from the
monitor. The contrasting colors of the slider and background also facilitate
this.

Below these is information on the next object. This gives the user the chance
to view the name, coordinates (including galactic), epoch, and local hour
angle of the new object before committing to moving the telescope. All
positions are from the source catalog, worklist, etc., and are not corrected
in any way. The exception is for solar system objects which are show at a
fictitious mean position. (This is the same coordinate system in which
ephemerides are often produced.)

The center column on the display shows more useful reference information.
The name, magnitude and spectral type of the current object are shown as
are the azimuth, zenith distance, parallactic angle and airmass of the
TELESCOPE.

The Epoch field shows the epoch of the telescope, command, and reference
positions. The pushbutton allows the observer to select among observed, mean,
and apparent positions (the latter with epoch). Note that the default is
observed position, which provides positions that most closely match the
telescope encoders. At this setting the telescope position displayed is
modified only by mount model and zeros.

Telescope mount information is also displayed and changeable. The mount model
being used to correct telescope position can be chosen from east and west
of pole (normal and "over axis") versions of each of the common foci as well
as a null model. Great flexibility was provided to the observer to correct
for mount models that become 'bad'.

The obstruction limits mask can also be chosen based on the secondary cage
in use (F9 or flip). The "basic" limits are the same used in the point
program and are provided as a failsafe. Due to the gross differences
between east and west of the pole, the software decides which side of the
axis the telescope is on and loads the proper map.

Note that it is always a Good Idea to insure that the mount model and
obstruction model are appropriate to the current telescope configuration
or, otherwise, are those you REALLy want to use. This is totally the OBSERVER's
responsibility! Let's be careful out there!

The upper central and upper right parts of the display show several important
items. The Mode field shows the current telescope motion mode. These are as
follows:
1) Standby - telescope not slewing or tracking.
2) Fixed Rate - telescope is tracking at a rate determined by the Rate pop-up
window described above.
3) Program - The telescope is moving under computer control and rate
computation. Slewing to a "next object" and tracking without fixed rates
will show this mode.
4) Stow, Fixed, Flat, and Zenith are shown when slewing to these types of
locations. At the end of this type of slew, the mode reverts to Standby
to prevent movement away from desired fixed position.

Also in this area are fields showing the last object file used (worklist or
ephemeris) and the command file loaded into memory.

On the right side of the display are parameters not directly related to the
telescope. The dome azimuth field comes from the dome computer and gives
confirmation that the dome is where it should be. This field flashes when the
dome is in motion. The focus field is read from the focus encoder and may or
may not be consistent from one visit to the mountain to another or from one
telescope configuration to the next.

Weather parameters pressure, tenperature, humidity, wind speed, and wind
direction come from the latest record in the weather file. (This information
is also available through the View->Weather History menu item.) Dew point
is derived from interpolation of standard tables.

ATOG angle, seeing, and transparency are not currently used as there is
currently no way to enter them into the system.

::::::::::::::
TCShelp_5.txt
::::::::::::::
TCS File Formats

There are several files of interest to the user of the TCS software. These
are mainly the worklist files, the ephemeris files, the command files,
and the object files. All are ASCII files and all are the responsibility of
the user to provide. Currently, there are no tools to manipulate these files.
(Well, there is some ephemeris generation software, but let's not discuss
that here.)

The worklist and ephemeris files are consistent with the sun version of point,
but not necessarily with VMS and earlier point incarnations.
-----------------------------------------------------------------------------

TCS Ephemeris Files

The ephemeris files can either contain a single object as they have
historically, or they can have many, each beginning with a header of the form

..object name [magnitude [spectral class]]

"..object" tells the program that this is a new object. "Object" is not
case-sensitive. The object 'name' should not be longer than 16 characters.

Magnitude is a real number, and is optional. Spectral type is a character
string (no spaces) up to 20 characters, and is also optional.

A file having a single object may also have a header, but it is optional.
The filename should be no longer than 16 character (excluding path). The last
of those 16 characters should be '.eph', as this is used in the TCSGui
File->Load/Transfer Ephemeris file name filter.

The ephemeris records are of the format;

Date RA Dec Parallax Epoch [unused fields for documentation only]

where the field are defined as follows.

Date
yyyy mm dd hh mm ss
-OR-
mjd

RA
hh mm ss.ss
-or-
hh mm.mm
-or-
hh.hh

(The last field MUST contain a '.', unless it is seconds. The last field may
have as many numbers after the decimal as needed.)

Dec
dd mm ss.ss
-or-
dd mm.mm
-or-
dd.dd

(The last field MUST contain a '.', unless it is seconds. The last field may
have as many numbers after the decimal as needed.)

Horizontal Parallax
ssss.ss (Arcseconds)

Epoch
yyyy.yy (Year and decimal fraction)

The ephemeris records are interpolated using a 3-point method.

The ephemeris entries' time tags must be evenly spaced in time, but can be
of any reasonable spacing, as long as there are no more than 1000 entries
per day. Obviously the entries must be in ascending order.
-----------------------------------------------------------------------------

TCS Worklist Files

Worklist files contain any reasonable number of commonly used object positions
as determined by the observer. (The TcsGui software will only display the
first 100 objects in a file.)

The format is as follows:

Reference-number Object-name RA Dec Epoch RA-proper-motion Dec-proper-motion

The fields are defined as follows.

Reference number - Must be present and can be any numeric, but is not used
by the TCS software.

Object-name: MUST BY PRECEEDED AND FOLLOWED BY QUOTES. An example is
"KAP 1 CET ". This is the biggest difference from the VMS point worklist
format.

RA
hh mm ss.ss
-or-
hh mm.mm
-or-
hh.hh

(The last field MUST contain a '.', unless it is seconds. The last field may
have as many numbers after the decimal as needed.)

Dec
dd mm ss.ss
-or-
dd mm.mm
-or-
dd.dd

(The last field MUST contain a '.', unless it is seconds. The last field may
have as many numbers after the decimal as needed.)

Epoch
yyyy.yy (Year and decimal fraction)

RA-proper-motion: annual proper motion in time seconds XXXX

Dec-proper-motion: annual proper motion in arc seconds XXXX
------------------------------------------------------------------------------

2.7m/HET Telescope Control System (TCS)
Monitor Resource Server
Command List
03 Dec 1997
15 Apr 1998

The TCS monitor program (tcsmon) is a telescope server of sorts. These
issued over socket (or serial interface) will produce information, change in
information display, or telescope motion. All communications is in ASCII for
clarity and ease of transfer.

The first column of the following alphabetical list can be interpreted as
follows:
blank - applies to both 2.7m and HET.
H - applies only to HET.
O - Obsolete command. Do not use. Code may or may not exist.
S - applies only to 2.7m (Smith) telescope.
X - old version of command, for comparison only.

H ccas
Loads ccas's ha and dec position into 'next'
currenthadec +hhmmss -ddmmss
define current telescope position
declareref 1|2 mode [ra dec]
mode: 0 - current telescope position
1 - commanded telescope position
2 - Offset from reference position 1 (Ref position 2, only)
ra,dec: the offsets from ref position 1 in seconds of arc.
displayepoch nnnn.nnn|-1
1800 < nnnn < 2200; -1 => currect epoch
domeenable 0|1
0=> disable; 1=> enable dome motion
domehome
move the dome to its home position
dumbtrack
Fixed rate tracking
emergstop
Emergency Stop
endfile
FOr workfile or ephemeris file transfer
ephemeris n filename
Tcsmon to start receiving the ephemeris named filename occupying position
n in the gui menu.
findfk5 zd_min zdmax mag_faint mag_bright
zd_min is lowest desired zenith distance (degrees)
zd_max is highest desired zenith distance (degrees)
mag_faint is faintest magnitude desired
mag_bright is brightest magnitude desired
H findfocus
Find 5 nearest stars from focus catalog.
flat
Loads flat's ha and dec position into 'next'
gui [off]
Tells tcsmon to send gui info packet on a regular basis (5 Hz, now).
The 'off' option turns off the gui packet transmittal.
H guiccas
Brings up maintenance gui for ccas subsystem.
guider
Tells tcsmon to send guider info packet.
H guidome
Brings up maintenance gui for dome subsystem.
H guifacility
Brings up maintenance gui for facility subsystem.
H guimirror
Brings up maintenance gui for mirror subsystem.
H guipfip
Brings up maintenance gui for pfip subsystem.
H guistructure
Brings up maintenance gui for structure subsystem.
H guitracker
Brings up maintenance gui for tracker subsystem.
SO hpmode 0|1
Hand paddle mode: 0=>analog; 1=>digital
iraf
Tells tcsmon to send iraf info packet.
jupiter
Make Jupiter 'next' object.
mars
Make Mars 'next' object.
mercury
Make Mercury 'next' object.
mntrecord
Record the current telescope commanded and observed position in a mount
model data file.
mntsearch req_reg req_prior req_minmag req_maxmag
Start mount model fk5 catalog earch for candidate stars.
req_reg - requested number of regions (or observations) to make.
req_prior - 0=star closest to center of region; 1=brightest star [?]
req_minmag - brightest desired magnitude
req_maxmag - faintest desired magnitude
moon
Make Moon 'next' object.
moveabort
Stop all jogging (2.7m) or all tracker motion (HET).
H moveabortdome
Stop dome motion.
H moveabortdomeshutter
Stop shutter motion.
H moveabortstruct
Stop structure motion.
H movedomeshutter
Open the dome shutter ('o') or close it ('c').
movefocus
Move focus motor to this position (%% offset?).
movenext
Move telescope to the 'next' position.
H movenextdomeaz
Move dome to the 'next' position.
H movenextstruct az
Move telescope structure to the 'next' position.
neptune
Make Neptune 'next' object.
nextazel dddmmss sddmmss
Set 'next' position to this az/el (converted to ha/dec).
nextbsc nnnn
Set 'next' position to Ra/Dec corresponding to this Bright Star Catalog
number.
nextconst alp con
Set 'next' position to Ra/Dec corresponding to this greek letter and
constellation name abbreviation
O nextdec sddmmss [ppp.ppp]
Set 'next' position dec axis value to this position and proper motion
(in arcsec/xxx). Incomplete if not accompanied by 'nextra'. Better
to use 'nextradec'.
H nextdomeaz xxx.xxxx
Set 'next' position of dome, in degrees.
nextephemeris filename objectname
Set 'next' object to this ephemeris and object (they can be the same).
nextepoch nnnn.nnn
1800 < nnnn < 2200. Accompanies 'nextra'/'nextdec',
nextfk5 nnnn
Set 'next' position to Ra/Dec corresponding to this Fundmental Katalog 5
number.
nextfocus nnnn
Set 'next' position to Ra/Dec corresponding to this focus catalog number.
nexthadec shhmmss sddmmss
Set 'next' to this hour angle / declination position.
nextic nnnn
Set 'next' position to Ra/Dec corresponding to this New Galactic Catalog
(IC) number.
nextmessier nnn
Set 'next' position to Ra/Dec corresponding to this Messier Catalog
number.
nextname
Set 'next' position to object having this common name (e.g. arcturus).
nextngc nnnn
Set 'next' position to Ra/Dec corresponding to this New Galactiv Catalog
number.
O nextra
Set 'next' position ra axis value to this position and proper motion
(in arcsec/xxx). Incomplete if not accompanied by 'nextdec'. Better
to use 'nextradec'.
X nextradec hhmmss sddmmss [xxxx[.xxxx] [xxx[.xxx] [xxx[.xxx]]]]]]
X Set 'next' to ra/dec, epoch. and proper motions (time and arsec / xxx).
X 1800 < epoch < 2200.
nextradec hhmmss sddmmss [xxxx[.xxxx]
Set 'next' to ra/dec, and epoch. Fifty char commands too short for other
information. 1800 < epoch < 2200.
nextradec2 xxxx.xx xxxx.xx xx.xxx xx.xxx
Set next ra and dec proper motion (tsec/year and asec/year),
parallax (asec), and radial velocity (km/sec).
nextref 1|2
Set 'next' to a reference position
H nextstructaz xxx.xxxx
Set 'next' position of telescope structure, in degrees.
nextworklist filename nnn
Set 'next' to specified object number in named worklist file.
override
Override telescope hardware limits. Must be repeated each time a limit
is encountered. 1=> HA axis; 2=> dec axis.
H overridestructaz n xxx.xxxx
Override structure azimuth as input (or not) from structure computer.
This effects the displayed az and 'telescope' coordinates.
n = 0 to use computer-read value; = 1 to override. xxx.xxx is override
structure azimuth in degrees. This value is read from structure computer
monitor. It DOES NOT contain the AZ offset!!!
pluto
Make Pluto 'next' object.
pointon
Enable 'point'-like output record.
pointoff
Disable 'point'-like output.
quit
Causes tcsmon to exit.
S rates slew search set guide hpstep hpra_polarity hpdec_polarity
0.5 < slew <= 2.0 degrees
0.1 < search <= 0.5 degrees
0.01667 < set <= 0.1 degrees
0.0 < guide <= 0.01667 degrees
0,0 < hpstep <= 60 arcsec - digital handpaddle step
digital handpaddle polarities: 0 => normal; 1=> reversed. [?]
S reboottcs
Reboots the TCS computer.
S reloadpmac
Reloads the pmac code.
saturn
Make Saturn 'next' object.
security nnn|aaa.bbb.ccc.ddd
Sets the security level of the user. Limited by security level assigned
to gui's host. Values can be 0-256, or -1 for lockout of other guis.
If numeric host address is given, security level is derived from its
entry in /data/lib/thosts.
setfocus nnn
Set the telescope focus counter to nnn. (Does not move focus.)
setfocusconf nn
Set the telscope focus configuration (e.g., 1=2.7m Cass F/9). Results
in reading appropriate mount model file.
setobstructconf nn
Set the telscope obstruction handling configuration (e.g., 0 =
Basic Limits). This results in reading appropriate obstruction mask file
(or in the case of "Basic limits", a point-like hardwired algorithm.
shutdowntcs
Halts the tcs computer.
stepclear
clear 'step' offsets
stepdec [s]xxxx[.xx]
Make telescope dec axis step by given number of arcsec (> -3600; < +3600).
stepfocus [s]xxxx[.xx]
Make telescope focus step by given number of units (> -1.e6; < +1.e6).
For 2.7m, units are encoder units (???); for het, units are mm.
stepra [s]xxxx[.xx]
Make telescope ra axis step by given number of arcsec (> -3600; < +3600).
H stepx [s]xxxx[.xx]
Make telescope x axis step by given number of mm (> -1000; < +1000).
H stepy [s]xxxx[.xx]
Make telescope y axis step by given number of mm (> -1000; < +1000).
stow
Sets the 'next' position to the telescope stow position.
H structureenable 0|1
Disable (0) or enable (1) telescope structure.
sun
Make sun 'next' object.
sunavoid 0|1
Turns sun avoidance option off (0) or on (1). Default is 'on'.
H tkrinit n|s|m
Init tracker: n=normal; s=search (full init); m=minimal (just connect)
H tkrmode l|r
Set tracker mode: l=local, i.e., from TS; r=remote, i.e., from TCS.
H tkrshutdown
Send shutdown command to tracker, so that it saves its position.
trackrates harate decrate
Track rates in arcsec/sec.
trkoff
Go into standby mode (tracking off).
trkon
Turn tracking on based on object mode (e.g., just move but don't
track if a fixed ha/dec, stow position, etc.)
uranus
Make Uranus 'next' object.
venus
Make Venus 'next' object.
version
Return the Tcsmon version number.
worklist nnn filename
Tcsmon to start receiving the worklist named filename occupying position
nnn in the gui menu.
wxunits 0|1
Change weather.unit display on all guis between metric (0) and
traditional or British ubits (1);
zero n|d|p|0|s razero deczero
Set the telescope axis zeros.
i - 'inquire'. Return computed zero values that 'new' would use.
I.e., 'new' without actually setting the values.
n - 'new'. Set the values to current observed-commanded.
d - 'default'. Set to tdefault zeros.
p - 'previous'. Set to the previous zeros.
0 - 'zero. Set the values to zero.
s - 'specified'. Set zeros to the specified values razero and deczero
in arcsec (> -3600, < 3600). This is only form to use the
razero and deczero values.
::::::::::::::
TCShelp_6.txt
::::::::::::::
Special Items Primarily for Maintenance

1) The TCSGui Special menu
-------

Set Current HA/Dec
-------------------
Sun Avoidance
-------------------
Take Data for Mount Model...
-------------------
To East Service
From East Service
To South Service
From South Service
-------------------
Show PMAC Status
Show Dome Status
Show Raw Encoders
Show Encoder History
-------------------
Terminate TCS Monitor
Reboot TCS
Shutdown TCS

The special commands are of help in setting up and maintaining the TCS system.
"Set Current HA/Dec" allows you to tell the computer where the telescope is
currently pointed, as a first cut at encoder zero point offsets. This step
will be necessary whenever the HA or Dec absolute encoders loose power or are
repositioned. The input HA/Dec can come from the old absolute encoder display
or from using levels to point the telescope at or near some known location
(like the zenith).

By default, sun avoidance is active. Currently, the telescope halts slews going
through a radius of 30 degrees from the sun. Note that 1) this does NOT ???
affect handpaddle motion, and 2) the radius can be changed by editting the
site file (to be described later). When moving the telescope around with the
dome closed, these precautions are not only unnecessary, but a nuisance. Thus
sun avoidance can be turned off.

"Take data for mount model" pops up a window similar to that for "FK5 stars
near the zenith", but with more options. Select the number of stars and
magnitude limits and push"search!". A scrolled list of candidate stars are
provided as is a skyplot with the stars and the limit mask. A file name
is produced based on date and time, and will be stored in /data/star.
To proceed, click on a star in the list or on the plot. Push "Go next" button
on the bottom of the window or in the command button area on the main window.
(The former does not always seem to work...) Look out for limit violation
errors in the command response area. Center the star and push the record
button. The program then loads the next star in the list as the next object.
If you are happy with the selection, just push "Go Next". Repeat as needed.

The service position selection move the telescope to and from the standard
service positions. Since getting to the service positions can be hazardous
from some positions of the sky, the commands are implemented via macros
which move in 2 steps, first to 0 ha, 0 dec and then to the service position.
The 'from' macros move fromthe service position to 0 ha, 0 dec. For safety
reasons, the automated positions come short of the actual service positions.
The user may need to use the hand paddle to move the telescope to the final
positions.

Note the TCSGui does not provide menu items for fitted o graphing the data.
This must be done separately. Invoke mntfit and mntgra as you would for
the Sun systems.

"Show PMAC Status" and "Show Dome Status" pop up windows with all the status
information available from these 2 sources. A particular status bit is on
if the background of the label is black.

"Show encoders" displays the raw incremental encoder information as returned
by the PMAC. "Show Encoder History" shows the same information in a scrolled
window at one second rates, in both decimal and binary formats. These tools
could potentially help locate encoder faults.

The remaining items allow the user to reboot or shutdown the control computer
(colossus). These duplicate items in the colossus console's root menu under
the maint account.

TCS Control Conputer File System

The TCS control computer's LynxOS file system shows features common to most
unix systems. Added to the file system structure have been directories required
to support the control system software.

The directory trees specific to this project are as follows:

/prod
/bin - all production binary files for the TCS.
/src - all source files for the TCS
- Note that production code is held in the RCS directories in
each of the following.
/jpl - jpl ephemeris code
/tcsgui_int - TCS GUI
/tcsmon_int - TCS Monitor
/tcsmnt - TCS mount programs: mntfit and mntgra
/tcs_scripts - scripts to perform printer, shutdown, and other tasks.
/utilib - Utility routines loaded by the above.
/docs - Various change documents and help documents (such as this)

/data
/cat - star and deep sky catalogs.
/lib - various site, mount model, and prediction files (including
jpl.dat, the binary jpl ephemeris file)
/mesg - tcsmon history files, showing commands executed and anomalies
detected.
/observer - observer-supplied ephemeris and worklist files, transferred
via tcsgui and tcsmon
/star - mount model observation files.

TCS Monitor File Usage

The TCS Monitor uses several files to create a flexible and consistent
suite of inter-related input and output files. The files used are as follows.

/data/lib/.thosts
The .thosts file follows the spirit of the unix .rhosts file, in that only
listed hosts are permitted control of the TCS Monitor commands. The
structure of the file is
aaa.bbb.ccc.ddd security_level comments(like host name)

where the currently-defined securities are:
192 = bit 8 & 7 - active local host: all priviledges
64 = bit 7 - inactive local host: display privileges only
160 = bit 8 & 6 - active remote host: all except 'Special' menu
priviledges
32 = bit 6 - inactive remote host: display privileges only
8 = bit 4 - unpriviledged remote host: display privileges only
1 = bit 1 - No priviledges at all. Might as well disconnect :-)
This will mainly be set by active gui to lock out all
"eavesdropping" - designed for the paranoid observer
N.B., Not yet implemented.
Note that no priviledge above 32 should be set here. Tcsmon determines
whether the connection is from its host computeR. The hostname found here
is numeric to avoid aliasing. This file should have attributes (like
.rhosts) of "-r--------" although the code does not yet demand this.

/data/lib/tcs_files
This is the mother of all files. It contains 'links' to other files vital
to system operations. Using this intermediary file avoids having to rename
mount and site files to a specific name when new ones are created.
An example of this file is this.

#
# File of files: contains pointers to all 2.7 m TCS files used by TCSMON
# All files are ascii.
#
# March 1996
#
site_file: site_27y1997m03d24t1838
2.7m_F/9: mask_27y1997m03d10t0000.f9
2.7m_F/9_over: mask_27y1997m03d10t0000.f9_over
2.7m_Flip: mask_27y1997m03d10t0000.flip
2.7m_Flip_over: mask_27y1997m03d10t0000.flip_over
2.7M_Cass_F/9: cxxx_27y1996m03d04t0000
2.7M_Cass_Over_F/9: cxxx_27y1996m03d04t0000
2.7M_Cass_F/18: cxxx_27y1996m03d04t0000
2.7M_Cass_Over_F/18: cxxx_27y1996m03d04t0000
2.7M_Cass_F/9_IR: cxxx_27y1996m03d04t0000
2.7M_Cass_Over_F/9_IR: cxxx_27y1996m03d04t0000
2.7M_Cass_F/18_IR: cxxx_27y1996m03d04t0000
2.7M_Cass_Over_F/18_IR: cxxx_27y1996m03d04t0000
2.7M_Coude: cxxx_27y1996m03d04t0000
2.7M_Coude_Over: cxxx_27y1996m03d04t0000
incremental_encoder_map: incm_27y1996m03d04t0000

All files listed are assumed to be in /data/lib.

Note that this file as well as the site file (description to follow) are
based on keywords. A variable name is not recognized by position in the
file, but by its keyword. Note that the keyword must be followed by ':'
and at least one space before the value. Comments start with a '#' in the
tradition of most unix files.

The incremental encoder map feature is not implemented.

/data/lib/site_xxyxxxxmxxdxxtxxxx

The TCS site file contains much of the information needed to control the
functioning of the TCS Monitor. If this file does not exist or is not
referenced properly, the program will not run. There are hardwired
defaults for the variables found in this file, but they may not be adequate
or useable.

A sample file is:
#
# 2.7 m tcs site file
#
# Note: the format is: variable name, value. The variable name can end
# with any separator character (such as : or =) as long as there is no
# space between the end of name and the separator. e.g, "site_id : 27"
# won't work.
# ${header}
site_id: 27 # site name (27 => 2.7m telescope)
longd: 255.97801 # telescope west longitude in degrees
latd: 30.68049 # telescope geodetic latitude in degrees
height: 2057.185 # telescope height above geoid
haincd2ct: 180000. # hour angle incremental encoder counts per degree
decincd2ct: 180000. # declination incremental encoder counts per
# degree
haabsd2ct: 8195.0 # hour angle absolute encoder counts per degree
decabsd2ct: 8192.1 # declination absolute encoder counts per degree
haabs_zpoff: 0.037073 # hour angle sky- abs encoder offset
decabs_zpoff: 29.563120 # declination axis sky - abs encoder offset
look_ahead: 0.00 # look ahead time for next prediction in sec
ha_stow: 0. # hour angle stow position in hours
dec_stow: -20. # declination axis stow position in degrees
ha_zenith: 0. # hour angle stow position in hours
dec_zenith: 30. # declination axis stow position in degrees
ha_flat: -0.6667. # hour angle stow position in hours
dec_flat: 30. # declination axis stow position in degrees
slew_rate: 1.0 # slew rate in degrees/sec
search_rate: 0.2 # search rate in degrees/sec
set_rate: 6.0 # set rate in arcSEC/sec
guide_rate: 1.0 # guide rate in arcSEC/sec
hp_step_size: 1.0 # digital hand paddle mode step size in arcSEC/sec
ha_track_rate: 15.041 # default ha track rate in arcsec/sec
dec_track_rate: 0.0 # default dec track rate in arcsec/sec
min_sun_angle: 25.0 # angle of sun avoidance; < 0 => advisory only
pmac_alive_nom: 187 # nominal value for pmac_alive when there are
# no errors
ha_abs_encoder: /dev/digi1 # serial port for ha absolute encoder
dec_abs_encoder: /dev/digi2 # serial port for dec absolute encoder
hand_paddle: /dev/digi3 # serial port for handpaddle controller
# box
focus_abs_encoder: /dev/digi5 # serial port for focus absolute encoder
dome_auto: /dev/digi4 # serial port for dome automation PC
weather: /ss/weather/data/latest_5min.dat # Weather data file
earth_orientation: /data/lib/ser7.dat # dUTC, X, and Y predicts
jpl_ephemeris: /data/lib/jpl.dat # JPL solar sys ephem (DE200)
pmac_params: /usr/local/src/TcsPmacVar.ivr # pmac parameters file
pmac_code: /usr/local/src/TcsPmacCode.pmc # pmac code file

Note that several of the important input files are named in this file,
including the JPL binary ephemeris file, and the weather file. The weather file
is actually on atlas (at this time) and is obtained via nfs.

The Series 7 files is ftp-ed from USNO every Thursday about mid day. The script
on atlas which preforms this function also ftp's the file to colossus.p

A note on the JPL ephemeris software:
The JPL binary file was created using software in /prod/src/jpl. The code and
ascii versions of the ephemeris were lifted from the JPL ftp site. Read the
documentation in the /prod/src/jpl directory to find the JPL site and vagaries
of implementation under Lynx. It should be noted that the c language versions
of all this code was ported. Due to difficulties with the EPC Fortran compiler,
it is not currently possible to have both c and FORTRAN do i/o from the same
program. This mean we need 'c' software in the TCS Monitor to read the binary
JPL ephemeris. Thus the software creating the binary files must also be in
c to insure a compatible binary file.

::::::::::::::
TCShelp_7.txt
::::::::::::::
Current program versions:

TCSGui - 2.7m Telescope Control System Graphical User Interface:

101798

TCSMon - 2.7m Telescope Control System Monitor:

101798

These versions must be used together for the most reliable operations.