TELSHELL USERS GUIDE

Created 01/01/90 TG
Updated 03/31/15 EF

Telshell is an enhanced version of the unix tcsh shell, which runs in all the xterm windows at FLWO. Telshell behaves as tcsh, with the addition of built-in instrument and telescope commands. It is used for:

Telshell capabilities include:

When you start up an instrument system with gokep (1.2m), gofast or gotres (1.5m), several windows appear. One of these is labeled Telshell. Many commands can be typed in Telshell, to control the CCD, telescope, filters and motors or lamps. More documentation is in the section for the instrument you are using.

Instrument Control Commands

These commands control the state of the detector. Which ones you wish to use depends on what instrument is mounted. Possible choices include keplercam, fast and tres. Please consult the documentation for the appropriate instrument.

Of special interest to this discussion are the commands "total, go, bias, flat, dark, and comp". These commands all instruct the instrument to expose for a given time. They are designed to work from the Telshell window, and to return control of the window back to the observer after starting the exposure. This is NOT what is needed in a script. For this reason a special instrument command was created only for use in script files. This command is "gowait".

The gowait command for the ccds takes the following form:

ccd gowait [exptime|repcount] [file type[suffix]]
where:
exptime is the length of exposure
repcount is the number of exposures (only for BIAS)
file type is the type of exposure (BIAS, FLAT, DARK, COMP)
suffix is single-letter filter suffix on file name (only FLAT)

The complete list of possible commands is

BEWARE OF "ccd gowait" with NO exptime! This starts a runaway infinite exposure, which stops only with a complete restart of the CCD system!

Telescope Control Commands

The telescope control commands all start with the "tele" prefix. Not all commands work on both telescopes.

Commands Common to 1.2m and 1.5m

tele coords
argument examples:
tele enable
This command takes no arguments; it slews the telescope to the next loaded coordinates. The telescope moves only after the enable is issued.

tele grab

Creates a fits file from the guider window (NOT TRES), stores it in /Realtime/guider/frames with a time stamp.

1.2m ONLY Commands

NEW 1.2m commands

ONLY Telshell

EITHER Telshell or any xterm

1.5m ONLY Commands

TRES ONLY Commands

NEW CALIBRATION SYSTEM:

OTHER COMMANDS

Telshell Script Writing Reference

Warning - Scripts are intended for experienced users who are intimately familiar with the operations of FLWO telescopes and instruments. Please feel free to ask Ted about the practicability of specific scripts. Also note the comments below regarding termination of scripts.

Scripts are sourced in Telshell for the following functions:

  1. Instrument Control
  2. Telescope Movements
  3. Unix Commands

How to run scripts

Scripts MUST only be sourced in a running telshell, not run as shell scripts! Because Telshell maps in shared memory with the other programs which comprise the Realtime System, invoking a sub-shell of telshell is an error. Telshell should only be started with the rest of the system. Other scripts run by telshell won't know about telescope or other built in commands! This same problem occurs if you attempt to source a telshell script into an xterm.

The correct way to run a script, for example a script named my.script, is "source my.script" Adding arguments to invocation will be discussed below. If the scripts resides in your home/scripts directory, use "source ~/scripts/my.script" There is an alias defined to ease this, it is called script. It will automatically fill in the /home/observer directory and source the script, for example "script my.script" does the same thing as the earlier example.

Writing Scripts

Use your favorite editor (emacs, vi, mg, etc) to create a file. The observer area has a subdir named scripts, designed to hold telshell script files. This would be a good place to store your script. So, if using vi, the command for observer would be "vi ~/scripts/my.script". Insert your script commands int his file, save the file. In the telshell window type "source ~/scripts/my.script". This should run the script.

Script Commands

Unix commands can be split into two group when using any shell. These commands are considered either "built in" or "system". With built in commands, the commands are part of the shell itself. With system commands, the shell executes the command in another process.

All instrument control and telescope movement commands are built into the telshell. Some other commands were already built into tcsh, like "pwd". This document will only attempt to cover the commands that were added as built-ins to the tcsh shell. Please consult man pages for tcsh(1) and csh(1) for more information about built in commands. Tcsh is a superset of csh, telshell is a superset of tcsh. All other "system" commands are beyond the scope of this document as well.

Putting scripts Together

Most people learn best from example, so here are a few:

KILLING A SCRIPT

It is difficult to kill a script! Telshell cannot be interrupted while a script is taking an exposure so it will not accept commands like "kill". Typing CTRL-C during readout will sometimes kill each individual exposure, and thus may be useful if there are only a few exposures left. If you would waste more time by allowing a long exposure or sequence to finish than by restarting the Realtime system, you should kill the system with command killcom (click here for more information) and, after the Telshell and Kep.err windows are gone, type gokep to restart. This problem may be avoided by inserting 5 second delays between each sequenced exposure in the script used, during which time one can type a CNTRL-C which will kill the sequence. The standard star and dome flat scripts above have such a feature. You may wish to include this feature in your scripts. If the telshell prompt is back and a long exposure is ongoing, type "sac" (for stop, abort, clear) in the telshell window. For the newer commands above, try typing "nabort" in any xterm.