TCC Operator's Manual

• Introduction
• Operation
  • Conventions
  • Starting, Restarting and Stopping the TCC Software
  • Actor Ports
  • Log Files
  • Stopping the Telescope
  • Batch Jobs (the Queue command)
  • Hardware Controllers
• Engineering
  • Data Files ($TCC_DATA_DIR) and Git
  • Earth Orientation Predictions
  • Specifying Instrument Data
  • Homing Mirrors
  • Moving Mirrors
    • 3.5m Tertiary
    • SDSS Primary
  • Telescope Modeling (telmod.dat)
  • Axes Limits (axelim.dat)
  • Software Tuning Parameters (tune.dat)
• Installing Software
• Managing and Updating Software
• Generating Message Keyword Manuals
• Troubleshooting
  • Telescope does not move, or goes to the wrong position
  • Earth orientation data too old
  • Communication errors (e.g. bad echo or xxx not recognized)

Introduction

This manual is intended for telescope operators and computer programmers. It explains how to start, stop, and maintain the Telescope Control Computer (TCC) control system.

Operation

Conventions

• Spherical positions are in degrees, including RA. The first axis is the equatorial angle (e.g. RA or longitude); the second axis is the polar angle (e.g. Dec or latitude).
• Azimuth is 0 south, 90 east. (This is somewhat unusual, but the more common convention is not a right-handed coordinate system.)
• Proper motion is arcsec/century; the equatorial component is dEquatAng/dt, so it may be large near the pole
• Radial velocity is km/sec, positive receding (but it rarely matters)
• All coordinate systems are right-handed, so azimuth os 0 south (which is unusual), 90 east
• TAI is MJD, seconds (not days)

Starting, Restarting and Stopping the TCC Software

Log into the appropriate tcc as user "tcc":

• tcc35m for the 3.5m telescope
• tcc25m for the SDSS 2.5m telescope

Set up the desired version in eups:

• lsst # to enable eups and the setup command
• Use just one of the following commands to set up the desired version of the TCC and its dependencies:
  • setup tcc # setup the current version
  • setup tcc -t test # setup the "test" version
  • setup tcc <version> # setup the specified version (use eups list tcc to see which versions are available).

To start the tcc: start up its actors, then start the tcc:

For the 3.5m telescope:

sec start
tert start
tcc start

For the SDSS 2.5m telescope:

prim start
sec start
tcc start

To restart the tcc or start a different version of the tcc: stop the tcc, restart the other actors, then start the tcc again:

For the 3.5m telescope:

tcc stop
sec restart
tert restart
tcc start

For the SDSS 2.5m telescope:

tcc stop
prim restart
sec restart
tcc start

To stop the TCC: stop the tcc, then stop the other actors:

For the 3.5m telescope:

tcc stop
sec stop
tert stop

For the SDSS 2.5m telescope:

tcc stop
prim stop
sec stop

You can stop or restart actors as needed, in any order, but:

• If you restart the tcc, you will have to reconnect the hub to it: in TUI type hub startNubs tcc
• If you restart a mirror controller, you will have to reconnect the TCC to it: in TUI type tcc mirror connect.

The full list of start, stop and restart commands for each actor is:

• start: start the actor (complains and does nothing if the actor is already running)
• restart: halt the actor if running, then start it again
• stop: halt the actor
• stopdead: kill the actor in a nasty way; use this only if stop fails

Actor Ports

If needed, you can communication with the tcc and mirror controllers using telnet. More than one user can be connected at the same time (e.g. you and the tcc or hub). Telnet to the appropriate machine using the appropriate port:

Telescope	Actor	Host	Port
3.5m	tcc	tcc35m	3500
	sec	tcc35m	3532
	tert	tcc35m	3533
SDSS 2.5m	tcc	tcc25m	2500
	prim	tcc25m	2531
	sec	tcc25m	2532
	az	tcc25m	2521
	alt	tcc25m	2522
	rot	tcc25m	2523

For example: telnet tcc35m 3532 to talk to the 3.5m secondary mirror controller.

Warning: do not talk to the axis controllers while the tcc is tracking or slewing. You will confuse the tcc and halt the telescope.

Log Files

3.5m telescope logs are on hub35m:

• TCC and mirror controller actors logs: /home/tron/logs/tcc35m/
• Command/reply streams for axis controllers, Galil mirror controllers and more: /home/monitor/logs/from.azimuth, from.altitude, from.rotator, M2, and M3 (where is Agile rotator?)

SDSS 2.5m telescope logs are on sdss-hub

• TCC and mirror controller actors logs: /home/logging/logs/tcc25m/
• Command/reply streams for MCP, Galil mirror controllers and more: /data/logs/from.MCP, to.MCP, from.25mM1 (where is M2?)

Stopping the Telescope

In case of an emergency: PUSH A RED EMERGENCY STOP BUTTON.

Please only do this in an emergency, because it is hard on the enclosure. If safety permits and you have a connection to the TCC try issuing an Axis Stop command first.

Batch Jobs

The TCC supports running batch jobs in the background via the Queue command. Batch jobs are python files in $TCC_DATA_DIR/jobs. Each batch job is one twistedActor.ScriptRunner script. These are very similar to TUI scripts, with some important differences:

• There is no graphical user interface. Thus there is no way to accept user input (though in theory the Queue command could be enhanced to accept additional parameters).
• To display messages to users, issue the TCC's broadcast command.
• ScriptRunner.startCmd and waitCmd do not accept an actor (the actor is always the TCC).

With this in mind, please see $TCC_DATA_DIR/jobs/example.py for an example, and read TUI's Scripting Manual for more information.

Warning: TCC batch jobs are run in the same event loop as the TCC itself. You can easily kill tracking by having your script use too many resources. If your script requires lengthy computations, run it as a thread using yield sr.waitThread. If your script needs to pause use yield sr.waitSec. If batch jobs do prove to interfere with tracking, it would be fairly straightfoward to modify the Queue command to run batch jobs as separate processes.

Hardware Controllers

The hardware controllers are small computers that talk directly to the axis motors and encoders, mirror actuators and so on. The TCC communicates with them in plain text via TCP/IP sockets.

Initializing a Hardware Controller

Exactly what initialization means to a controller depends on the controllers. However, in general initializing will stop any motion (if applicable) and generally put the controller into a known sensible state. Initialization is a normal thing to do to a controller. Initialization is done via the commands specific to each controller. For example Axis Init and Mirror Init. If initialization fails, you may have to restart the hardware controller.

Direct Communication

To send a brief command to an axis or mirror controller, use the Talk command.

For a more extensive session with a mirror controller, disable the collimation process in the TCC with Proc Disable Collimate (to avoid confusing the TCC) and telnet to the mirror controller port. The mirror controllers support multiple users, so you need not worry about the TCC's connection.

For a more extensive session with an axis controller, stop the axes in the TCC, then use talk2boxes. (Eventually we expect that direct telnet will work, but it will not work while we are stuck using the terminal servers.)

Engineering

Data Files ($TCC_DATA_DIR) and Git

The directory $TCC_DATA_DIR data directory, which points to ~/tccdata, contains the following configuration files:

• axelim.dat: axis limits
• earthpred.dat: earth orientation predictions
• telmod.dat: the telescope pointing model
• tune.dat: tuning parameters
• posRefCatalog.dat: catalog of pointing reference stars
• inst/ a directory of instrument data files
• jobs/ a directory of batch job files

The data directories for the 3.5m and SDSS 2.5m tccs are git repositories hosted here: 3.5m and SDSS 2.5m. Using git makes it easy to see how data files have changed over time. Here are some useful git commands for keeping the data up to date:

• git status shows you which files have changed. It will also show untracked files (files that are in the directory but are not tracked by git). You can track additional files using git add filepath.
• git commit -a records the current state of all files that are part of the repository. This records the changes locally.

To view changes I suggest running git gui in directory $TCC_DATA_DIR on the TCC. This gives a nice graphical view. (If you have a clone of a git repository on a Mac, then it is even nicer to view changes using the free program SourceTree).

Earth Orientation Predictions

The TCC software requires earth orientation predictions to operate at full accuracy. The data is read from $TCC_DATA_DIR/earthpred.dat and this this section describes how to keep that file up to date. Predictions are regularly e-mailed to us by the U. S. Naval Observatory, as a file called "IERS Bulletin A". Data from this bulletin is extracted by a utility program, and written out in a form the TCC software can use.

To update the predictions:

Obtain a copy of IERS Bulletin A. Normally this is electronically mailed to the site about once a week. If that fails you can download the bulletin from the US Navel Observatory. As of 2014-05 the web page for bulletins is http://www.iers.org/IERS/EN/Publications/Bulletins/bulletins.html and the link for the latest IERS Bulletin A is http://datacenter.iers.org/eop/-/somos/5Rgv/latest/6. If you save the file to $TCC_DATA_DIR/iersbulla.dat then earthFilt.py will find it automatically.

Convert the data to a format suitable for the TCC:

$ earthFilt.py

If the TCC software is running you may load the new data using the TCC command SET TIME. Otherwise it will be loaded automatically at startup.

Details

IERS Bulletin A contains predicted values for the rotation of the earth, as UTC - UT1, and pole wander (used for a small correction to longitude and latitude). It also gives the exact value for TAI-UTC at the start of the predictions. IERS Bulletin A is set up for the convenience of people who keep UTC, and so want UTC-UT1. But the TCC uses TAI (and TAI-UT1); TAI is smoothly varying, whereas UTC has occasional abrupt one-second changes, called "leap-seconds". Thus the TCC has a conversion utility that derives TAI-UT1 (and TAI-UTC) from the bulletin's UTC-UT1 predictions and the initial value of TAI-UTC. It deduces the presence of leap-seconds by noting discontinuities in the value of UTC-UT1.

The TCC software reads Earth orientation data from $TCC_DATA_DIR/earthpred.dat. The TCC extracts the predictions for yesterday, today, and tomorrow and saves these predictions to the Earth global data block. You may update the predictions file at any time. The new file will be read when the TCC next synchronizes its clock to the time reference, and you may force this event (though that is rarely necessary) by issuing the TCC command SET TIME.

The current values of TAI-UT1 and pole position are obtained by reading the Earth block and performing the appropriate interpolation. There is a TCC subroutine which does all this.

Specifying Instrument Data

Introduction

Information about the position and orientation of the instrument and guide camera is contained in instrument data files, contained in the $TCC_DATA_DIR/inst/ directory. This information is necessary for proper tracking, guiding and pointing data collection. Some of the information is a matter of taste or convention, e.g. the desired center of an instrument, but much of it must be carefully measured for the telescope to operate correctly.

The instrument data is distributed among four kinds of files. These are discussed in File Types. The names of the files determine the names used in the SET INSTRUMENT command, as explained in File Names . For help measuring instrument parameters, see the Instrument Data Fitting manual.

Instrument data files are only read during a SET INSTRUMENT command. Hence to change the values the TCC is actually using, you must not only edit the file(s), but also load the new data by issuing the appropriate SET INSTRUMENT command.

File Types

There are four kinds of instrument-related data files: default, instrument position, guide camera view, and instrument. Each instrument/guide-camera-view combination has at most one of each kind of file associated with it. The files are read in the order listed, with data from later files overriding data from earlier files.

• There is only one default data file. This file is read before all others, and sets up a reasonable null instrument (e.g. no guider, no instrument rotator).
• Instrument position files contain information appropriate for all instruments mounted at this instrument position (e.g. Nasmyth #2). These files are optional. For instruments which are permanently mounted at a particular instrument position, you may prefer to place all the data in the instrument file and omit the instrument position file.
• Guide camera view files contain data for each guide camera view other than the default view. The default view information is contained in the instrument-position or instrument-specific data file.
• Instrument files contain data about the particular instrument.

The format is identical for all of these files. This provides maximum flexibility, but the heavy overlap also means you must be very careful about which entries you specify and which you leave unchanged (by omitting them or commenting them out). The files are loaded in the order listed above, and in the event of a conflict (two files setting a value differently), the last data seen is used, without warning. Note that the default file and instrument file are always read, but the instrument position file is only read if it exists, and the view file is only read if a non-default view is specified.

File Names

The name of each instrument and view (as used by the SET INSTRUMENT command) is specified by the name of the corresponding instrument-specific or view data file. Hence the naming of instrument data files is very important. The files are named as follows:

• DEFAULT.DAT for the default data file
• IP_pos.DAT for instrument position data files
• V_pos_view.DAT for guide camera view data files
• I_pos_inst.DAT for instrument data files

where:

• pos is a three-letter code describing the instrument position. These codes are described in the file TINC:INSTDEF.FOR
• inst is the name of the instrument, and must be unique. It is used in the command SET INSTRUMENT=inst
• view is the name of the guide camera view, and is used in the command SET INSTRUMENT/VIEW=view

All files are kept in the directory $TCC_DATA_DIR/inst/

Special Cases

No Instrument Rotator

The "angle from the instrument x axis to the rotator x axis" is degenerate with the rotator's "fixed physical position" (except there may be a sign change). I recommend setting the rotator's "fixed physical position" to zero and measuring "angle from the instrument x axis to the rotator x axis" as described below.

The Guide Camera is the Instrument

This is a common configuration for measuring telescope pointing. It is especially common right now, when we don't have a working offset guider. In such a case, some data fields are zero, and other fields are clones of existing fields; if you ever change one field, you must remember to change its clone!

Position of the guide camera in the guide image frame = position of the center of the rotator in the instrument frame. If you change one, remember to change the other!

Angle from the guide image x axis to the guide camera x axis = angle from instrument x axis to rotator x axis. If you change one, remember to change the other!

There is no guide camera positioner. All position and orientation data for it should be set to zero.

Interactively Tweaking Instrument Data

InstEdit is a simple utility which allows you to interactively vary certain elements of the current Inst global data block. This may help you try out or play with values for an instrument data file. Once you have determined the correct values, you must still manually edit them into the appropriate instrument data file.

To run InstEdit, exit from the TCC (or better yet, open a second connection to the TCC, one for TCC commands, one for InstEdit) and type: $ InstEdit. For more information, see the TCC Utilities Manual.

Don't forget to edit your changes into the appropriate instrument data files when you are through, else all changes will be lost.

Homing Mirrors

The basic procedure is as follows (but see the note for the SDSS primary).

• Disable collimation. From (S)TUI: tcc proc disable collimate
• Slew the telescope to the altitude for homing for the mirror in question.
• Telnet to the appropriate mirror controller host and port, e.g. for the SDSS secondary: telnet tcc25m 2532
• Home the axes using the commands, in order.
• After homing, re-enable collimation using: tcc proc enable collimate

While homing, watch the mirrors. If anything goes wrong, abort homing using mirror controller command: stop

You can abort the relax job (or any job) using tcc queue stop

While homing you should see the mirrors do the following:

1. The axes being homed first move at full speed until they hit the reverse limit/home switch. As each axis reaches the switch it will stop. This is the most dangerous phase of homing; the mirror is most at risk and any problems are most likely to show up. Things to especially watch for:
   • Motion must be towards the reverse limit switch (the actuator gets shorter, position values get smaller). If motion is in the other direction, halt immediately and fix the problem (misconfigured Galil or reversed motor wiring). Obviously this problem is most likely to occur after work on the Galil or actuators.
     • If you are watching motion with linear gauges, be aware that their signs may be reversed (though this indicates a setup problem that should be fixed!). You should figure this out before starting homing or watch the actuators directly so you know if there's a problem with the direction of motion.
   • Motion stops in any axis before it reaches the reverse limit/home switch.
   • Motion stops in all axes for several seconds (while the Galil is still looking for the reverse limit switches).
   • One thing not to panic about:
     • You are homing the axial actuators and they seem to be moving correctly and seem to correctly reach their reverse limit switches and stop. But as soon as the last axis arrives, the Galil, instead of going on to the next phase, prints a warning that not all axes have reached the first limit switch and tries again.
     • That "as soon as" is the crucial point. If there is a delay after all axes arrive, that always means trouble: stop the axes and investigate. But if the warning message comes right away, there's no need to panic. Go ahead and let it try again.
     • This second try should be very quick. If it's not, stop the axes and investigate.
     • Occasionally the automatic retry is not sufficient and homing will fail. In such a case, go ahead and try homing one more time before giving up.
     • The issue is that there is some crosstalk between the axial actuators (motion in one can cause another to move relative to its reverse limit/home switch). That is the reason for the automatic retry.
2. As soon as all axes touch their reverse limit/home switches, a message is printed and the axes being homed move a short distance away from the reverse limit switch. This should be uneventful and quick. However, if a forward limit switch is broken, this is where it will show up: you'll see an error message and homing will halt.
3. The axes being homed move until they are on a full step. This is a painfully slow process and you may not see any motion at all. Just give it time. Errors here are extremely unlikely and indicate some sort of configuration problem (such as the wrong # of microsteps/step) or an electrical problem with the on full step signal.

Moving Mirrors

This section describes how to move mirrors for collimation and other engineering purposes. Before moving a mirror, it is important that you understand how it is mounted. There are some quirks and gotchas that may not make sense otherwise.

The basic procedure is:

• Disable collimation by sending tcc proc disable coll from TUI's log window.
• Slew the telescope to the desired altitude (if relevant).
• Set the mirror orientation as desired by commanding the appropriate mirror controller. For example, you can send the following commands from TUI's log window:
  • tcc talk sec "move 987, -23.5, 65.2, 57.6, -3.4"
  • tcc talk sec "offset 112, 34, -12.3"
• See the Mirror Controller Actor manual for more information about the commands.
• When you are done, re-enable collimation by sending tcc proc enable collimate from TUI's log window.

Mirror-Specific Information

Before moving a mirror it is very important to understand how it is physically supported. Otherwise you may induce stresses in the mirror, deforming the surface (especially a problem for the SDSS Primary) or the resulting motion may not be at all what you expect.

All on-axis mirrors (all mirrors except the 3.5m tertiary) use the following coordinate axes. With the telescope at the horizon, and with you standing behind the primary mirror looking through the hole in the primary at the secondary:

• x is to your right
• y is up
• z is from the sky to the telescope (i.e. toward you)

Hence:

• +x tilt (tilt about x from y to z) brings the top of the secondary mirror towards the primary or the top of the primary towards its mirror cell
• +y tilt brings the left hand side of the secondary mirror towards the primary or the left-hand side of the primary mirror towards its mirror cell

Hardware-specific limitations and unusual features of the mirrors are as follows:

• 3.5m Tertiary
• SDSS Primary

3.5m Tertiary

There are three axial actuators and no transverse actuators. Transverse position is maintained by a set of fixed links, so you can only command piston, x tilt and y tilt. (With the old TCC, when commanding tertiary mirror piston it was necessary to also command an equal amount of y translation. That is no longer the case.)

The coordinate system for the 3.5m Tertiary is unusual because it is desired that x/y tilts move the image sideways or up and down, rather than in the funny arcs that would result using the coordinate system for on-axis mirrors. Thus:

• z is towards the instrument port.
• y is towards the secondary mirror.
• x is parallel to the primary mirror, such that x, y, z is a right-handed coordinate system

  Thus:

• +piston moves the mirror towards the instrument port by the specified amount. However, the mirror is constrained to move along its axis, so as it moves closer to the instrument port it also moves closer to the secondary mirror; the net axial motion is sqrt(2) * piston.
• +x tilt moves images towards the primary mirror.
• y tilt moves images parallel to the primary mirror, like tertiary rotation.

To put it another way, with the telescope at zenith, if you are standing at an instrument port looking in at the tertiary then:

• x is to your right, y is up and z is towards you.
• +x tilt moves images down.
• +y tilt moves images to your right.

SDSS Primary

The SDSS primary mirror is supported by four sets of air-actuated belloframs. Three axial actuators and one transverse "vertical" (y translation) actuator adjust the hard points for the servo system that drives the belloframs. Two transverse "lateral" links adjust x translation; one is mounted near the top of the mirror (at horizon) and the other at the bottom. The lateral links act through air-actuated force fuses which release automatically whenever the lateral links move, as otherwise the lateral actuators would stall. The transverse belloframs have bearings to allow free motion, but the axial belloframs have a fairly high friction coupling to the back of the mirror.

The primary mirror cannot simply be translated at will; the friction is too great in the axial belloframs. The mirror may not move the full distance and in any case will have residual stresses that deform the surface figure. Piston and reasonably small tilts should be fine. To move the mirror in translation one should first move the actuators and then relax the support system as follows:

• Slew the telescope to roughly 80° altitude; the idea is to have the telescope nearly vertical while leaving a little force opposing the transverse vertical actuator.
• Relax the primary mirror using TCC command Queue Run=Relax. This repeatedly lowers the axial actuators and returns them to their current position, homing the actuators on the last lowering.
• Monitor the mirror motion (directly or via the linear gauges) to be sure the mirror does not go into sustained oscillation.

Telescope Modeling

The TCC software uses a "telescope model" to correct for various repeatable hardware errors, such as flexure of the secondary mirror support, and non-perpendicularity of the azimuth and altitude axes. The model contains a term for each identified hardware error. The coefficients for the model are determined empirically, by measuring pointing error, and fitting the result to the model using tpoint.

The model is contained in the TelMod global data block. TelMod is set at startup from file $TCC_DATA_DIR/telmod.dat, and remains fixed unless somebody explicitly changes it (as described below under "Load...").

The procedure for taking pointing error data and fitting a model is as follows:

• Set the proper instrument using TCC command Set Inst=inst.
• Run the TUI scripts Telescope: Pointing Data. Note that TUI has a manual page for this script.
• Copy the resulting pointing data to TCC directory tccdata/ptdata/ (you may also analyse data on other computers that have tpoint installed, but this manual does not discuss that).
• Analyze the pointing error data with tpoint.

To analyze your pointing data:

• log into the tcc as user "tcc"
• cd tccdata/ptdata
• tpoint
• inmod ../telmod.dat
• indat pointing_data_file_name (with the ".dat" suffix)

Then fit the model. See the tpoint manual or tpoint help for more information. You may add or delete terms, though please be very cautious about doing so.

To update the TCC's pointing model:

• outmod ../telmod.dat (save the model)
• telnet localhost 3500 (telnet to the tcc, or use TUI if you prefer)
• set block telmod/in=telmod (load the new telescope model)

When you are done taking pointing data and possibly modifying the pointing model, please save the results to the tccdata git repository:

• git status (make sure your new pointing data files show up as not added, and
• git add *.dat (add the new files)
• git commit -a (commit all files that have changed)
• git push (push changes to the remote repository)
• If git push fails because the remote has changed, then git pull and go back to the git commit -a step.

Axes Limits (axelim.dat)

The TCC has an extensive set of motion limits to protect the telescope. These include position, velocity, acceleration, and jerk limits for the azimuth and altitude axes, instrument rotator, and guide camera positioner. They also include position (only) limits for the primary, secondary and tertiary mirrors and guide camera. The TCC's limits only apply to motion requests by the TCC. The axes controllers have their own limits, which they will not exceed.

Position limits behave in a straightforward manner. If a move is attempted which violates position limits of the TCC or an axis controller, the motion is rejected with an appropriate error message. Under normal circumstances only the TCC should ever complain; an axis controller's limits will only come into play if the TCC's limits are made too broad (a serious configuration error) or the user bypasses the TCC and talks directly to the axis controller.

Regarding velocity and acceleration, the TCC must leave some headroom between the TCC's and controller's limits. With insufficient headroom, the axes controllers will be late finishing slews. This is a serious problem, as the TCC pre-computes slew paths, and relies on the axes controllers following the paths accurately and arriving on time. Note that the axes controllers do not complain if velocity or acceleration are exceeded during a move. They simply reduce the speed or acceleration as required and continue trying to keep up as best they can.

Jerk (the rate of change of acceleration) is only limited by the TCC, and then only when computing a slew. The limit may be set to practically anything. Its main purpose is to protect people from abrupt motions; it seems a bit unlikely that the motors can introduce enough jerk to cause problems for the equipment.

Specifying Motion Limits

All motion limits are stored in the AxeLim block. Most limits are fixed; these are read from the file $TCC_DATA_DIR/AXELIM.DAT when the TCC software starts up and then left alone. Some limits depend on which instrument is selected, and these are set in the same fashion as all other instrument-specific data.

To change fixed (instrument-independent) limits: Edit the file $TCC_DATA_DIR/axelim.dat. Load the changes into the TCC software by issuing the TCC command: set block axelim/in=axelim Set the current instrument again (to update instrument-specific limits).

To change instrument-specific limits see Specifying Instrument Data.

Software Tuning Parameters

Introduction

The Tune block contains values used to "tune" the operation of the TCC software. These values can usually be left alone, but may require adjustment if the hardware changes, or if something is not working correctly. The various tuning parameters are described below (grouped into several general categories).

To change tuning parameters, edit the file $TCC_DATA_DIR/tune.dat. For your changes to take effect, you must then load the file by executing the TCC command: set block tune/in=tune

Installing Software

Note: you must configure the TCC computer's clock to keep TAI (not UTC). This requires an NTP server that keeps TAI (which can fairly easily be set up if you have a GPS clock). An alternative is to rewrite the function tcc::tai to read UTC and convert it to TAI.

• Install the minimal LSST software stack:
  • Follow the installation instructions for the current release. This installs anaconda python, scons, eups and a few other packages.
  • Set up the LSST software stack using: source $LSST_HOME/loadLSST.sh. On tcc35m-1-p you can us alias "lsst" to do this.
• Install the following extra LSST packages. The procedure is the same for each: eups distrib install <packagename>:
  • ndarray
  • matplotlib
  • scipy
• Make sure LSST python is the one being used, e.g. using which python.
• Install Twisted Framework using pip: pip install twisted
• Git clone the tcc package.
  • It is served at bitbucket: git@bitbucket.org:csayres/pytcc.git
  • Don't try to build it yet; download it because it contains a utility handy for installing slalib and tcSpk (neither of which come with good make files).
• Install slalib:
  • Use tcc/utils/prepareTCSpk/prepareSlalib.py to massage the freshly unpacked software.
  • cd into the slalib dir
  • build using: scons
  • install using: sudo scons install
• Install tcSpk similarly to slalib:
  • Use tcc/utils/prepareTCSpk/prepareTCSpk.py to massage the freshly unpacked software.
  • cd into the tcSpk dir
  • build using: scons
  • install using: sudo scons install
• Install RO using pip install ROcode>
• Install and eups declare actorkeys, opscore, external, and twistedActor:
  • actorkeys, opscore and external are available from SDSS svn: svn+ssh://sdss3svn@sdss3.org/repo/ops/PACKAGE_NAME/trunk
  • twistedActor is available from github: git@github.com:r-owen/twistedActor.git
  • These are all pure python packages, so they don't need to be built, just unpacked and declared:
    • Download and unpack
    • cd into the directory
    • Use eups declare -r . name version --current where:
      • name is the name of the package, e.g. opscore
      • version_ is the version as known by eups. For a release the version should be the release version number. For a git clone I recommend git. For an svn trunk checkout I recommend trunk.
• Install and eups declare coordConv:
  • Clone coordConv. Presently it is served at github: git@github.com:r-owen/coordConv.git
  • Build it as per its instructions
  • Eups declare it using: eups declare -r . coordConv version --current or install and declare it using: scons install declare version=version
• Install and eups declare tcc:
  • You already cloned it above.
  • cd into the dir
  • Setup using: eups setup -r .
  • Build using: scons
  • Eups declare it using: eups declare -r . coordConv version --current or install and declare it using: scons install declare version=version
• Generate startup scripts for the TCC and its mirror controllers
  • setup tcc
  • cd /usr/local/bin or wherever you want the startup scripts to live
  • makeTCCStartupScript -h to see the accepted telescope names
  • makeTCCStartupScript telescope >tcc
  • makeMirrorCtrlStartupScript -h to see the accepted mirror names, then for each mirror (where shortName is prim, sec or tert):
  • makeMirrorCtrlStartupScript mirror >shortName
  • cd /usr/local/bin
  • chmod +x tcc shortName1 shortName2...

    For example:

    cd /usr/local/bin
    makeTCCStartupScript 35m >tcc
    makeMirrorCtrlStartupScript sec35m >sec
    makeMirrorCtrlStartupScript tert35m >tert
    cd /usr/local/bin
    chmod +x tcc sec tert
    

• Create the directory for TCC data and set environment variable TCC_DATA_DIR to point to it.
  • Create a directory to contain TCC data.
  • Create files axelim.dat, earthpred.dat, telmod.dat and tune.dat, as described elsewhere in this manual. You can also get starter files from Apache Point Observatory.
  • Create a subdirectory named inst. Fill this with instrument data files for your various instruments.
  • Create a subdirectory named jobs. This can be empty until you have batch jobs. Apache Point Observatory can provide at least one representative batch job.
  • Set environment variable TCC_DATA_DIR to point to it (e.g. in ~/.bash_profile).

Managing and Updating Software

Individual software packages are installed and managed using git and eups (scons commands use eups under the hood). Type "lsst" at the command line to setup the eups environment. Note it is expected that all packages have been initially eups declared (see Installing Software) by the time you get here! Also note that git and eups are separate systems, so it is up to the human typing to keep versions/tags coherent between the two.

Software updating procedure

1) When code is ready for a new tag (beta or otherwise) use git:

• update the python __version__.py file
• update the version history html file in the package's doc directory
• git commit with a commit message including the tag number
• "git push"
• "git tag versionNumber"
• "git push --tags"

2) Update code on TCC machine.

• Pull updates from repo: git pull or svn up
• If the recent updates are "beta" updates, do not install via eups/scons. Use setup tcc -t test (this sets up the current state of git/svn products) for testing prior to installation. After successful testing, git tag a non-beta version and push again.
• Install a new eups-managed package version and make it current:
  • If scons is available (coordConv, twistedActor, mirrorCtrl, tcc):
    • setup package and run unittests. From within the package directory: "setup -r ." --> "scons --clean" followed by "scons".
    • "scons install declare version=packageVersion current"
    • Note packageVersion should match the git tag, __version__.py, etc. It's up to the typest to keep these straight!
  • If scons tools are not available (eg, RO, actorkeys):
    • Copy the code to the installed location (choose the same location scons does). For svn packages, svn export is a good idea (to freeze the code)
    • "eups declare -r pathToInstalledLocation packageName packageVersion current".
    • Again packageVersion should match that of git.
    • For opscore and actorkeys, treat svn revision numbers like tags

Some Useful Commands

• git tag tagnumber

  Tag the current state of a git repo. Do this for any new version of code (including beta versions)

• git push --tags

  Tags must be pushed to the remote repo explicitly.

• git checkout tagnumber

  Move the repo to a specific tagnumber.

• git checkout master

  Move the repo to the most recent commit.

• eups list -v

  Show a complete list of all packages managed by eups. This will also indicate which packages are setup (if any), where the packages reside on disk, as well as all versions and tags available. Don't underestimate this one, I use it all the time to make sure things are set up correctly.

• setup packageName [packageVersion] [-t tagName]

  Setup a package. If neither packageVersion nor tagName are supplied, the current package is setup. Only a few tagnames are allowed: tcc, and test are among them.

• setup -r . [-t tagname]

  Setup the package in the current directory. If -t is supplied give it a tag name. Only a few tag names are allowed: tcc, test are among them.

• eups declare -r pathToPackage packageName packageVersion

  Declare a new version for a package. pathToPackage should be a natual location, usually in a common directory with previous versions of the package. A good strategy is to copy the complete package from the working git or svn repo to pathToPackage before declaring it.

  This will make the new version visible in eups list, and available for use with setup.

• eups declare packageName packageVersion current

  Make this version of the package current.

• eups undeclare packageName packageVersion

  Undeclare a packageVersion, wiping eups' memory of it, the code is left on disk.

• eups remove packageName packageVersion

  Equivalent to undeclare the version and delete the code from disk.

• scons --clean

  Remove all built software and unit test results

• scons [-j 1]

  Build all software and run unit tests. If unit tests are mysteriously failing try using the -j 1 flag to force all tests to be run on a single processor. This seems to be required occasionally on tcc35m. Many of the tests are necessarily asyncronous, and running on a single processor seems to help. Unit test and corresponding logs are stored in tests/.tests, you should look in there after building software. Try "ls tests/.tests/*failed" to identify failed tests after building.

• scons install declare version=packageVersion [current]

  Use this command from within any scons-managed package to declare a new version from the current state of the current directory. If current is specified with the command, this new package version will be made current. Code is automatically copied to a logical location before it is declared.

Generating Message Keyword Manuals

The Message Keyword manuals for the tcc and mirror controllers are generated from the keyword dictionaries in the opscore package, as follows:

• setup the tcc package (mirrorCtrl package suffices if that's the only package whose documentation you want to update)
• $ACTORKEYS_DIR/doc/describe.py --actor=mirror --tohtml=$MIRRORCTRL_DIR/doc/messageKeywords.html
• $ACTORKEYS_DIR/doc/describe.py --actor=tcc --tohtml=$TCC_DIR/doc/MessageKeywords.html
• Hand-edit each file to provide more useful title and header.
• Upload the result to the documentation server.

Troubleshooting

Telescope does not move, or goes to the wrong position

Check the status of the TCC with Show Status.

• AxisCmdState tells you what the TCC is asking each axis controller to do and AxisErrCode provides a reason if an axis is halted. See the TCC Message Keywords Dictionary for more information.
• If the axis controllers themselves are unhappy, you will see Bad<Axis>Status or Bad<Axis>DTime. You can look up the status bits in the Axis Controllers manual. Bad<Axis>DTime can be fixed by initializing the axis controller (though an occasional sporadic error is normal on the SDSS, at least as of 2002-05-22).
• Compare TCCPos and AxePos. During a slew, TCCPos indicates the target position, so it may be very different from AxePos. However, while tracking these two sets of numbers should be very similar, and if they are not, it indicates that the axes are not moving correctly. (If TCCPos is NaN for any axis, that axis is not being asked to move, which should also be indicated by AxisCmdState and AxisErrCode).

If the TCC appears to be doing what you asked of it and the axis controllers are happy, then check the position you specified with Show Object/Full. If the position or coordinate system looks wrong, check your track command very carefully. Did you specify the correct coordinate system?

Earth orientation data too old

Update the earth orientation predictions as per the procedure described here.

Communication errors (e.g. bad echo or xxx not recognized)

Clear the communications channel by initializing the controller. If the init times out, the odds are that the link or controller is down; check wiring, power, etc. If the init fails due to garbled communications then the terminal server or controller may be sick.