----------------------------------
Detailed listing of otcom commands
----------------------------------
  
Download DSP code:
------------------
  df         - this tries to turn off the high volts and then
                 downloads the code to both timing and utility boards.
                 The default is optic4.lod and opticlub.lod found in
                 /usr/local/inst/dsp.  The environment variable LODPATH
                 (default /usr/local/inst/dsp:.) governs where DSP files 
                 are sought.

Power on:
---------
  pon        - turns on the high volts (i.e. +/-16 and +36. The idea
                 is that we want the +5V on and stable so that the DACs 
                 which will supply voltages to the CCD are stable before 
                 their power is turned on.)
  poff       - turns off the high volts.
  tdl        - test data link, pings the CCD controller

Verify temperatures and voltages:
---------------------------------
  temp       - view temps of CCD and electronics
  temp -105  - set CCD regulation temp to -105
  volt       - view voltages

Status:
-------

  status     - shows what's doing, crowded but pretty complete:

Frame: 001   File prefix: '/tmp/ccd'   Filter 1 'R'
Science:   bin 1x1, origin (0,516), size (2048,1536), 32 bias, 4 amp, texp 1.00
Guide:     bin 2x2, origin (1,1), size (16,16), geom 0,2 0,2, texp 0.020
GS at:     0.0 0.0   0.0 0.0   0.0 0.0   0.0 0.0
Params:    nwipe 1, shut 1, read 1, wrdat 1, track 0, wrot 0, wrvid 0 
OT track:  alg 0, wait 5, gain 1.00, max 8, regions 11111111, wgt 2.00
Tel guide: on? 0, min 2.0, gain 0.35, PA top 0.0, EccwN? 1

  The first four lines are relatively self explanatory, although it's
  important to realize that the guide box specification has two parts.
  There is a common "bin origin size" for all stars, which is used in
  reading out the little regions around them.  The "bin" and "size"
  define the box parameters, and the "origin" defines where the boxes
  are shifted prior to readout.  An origin of (0,0) or (1,1) is good.

  The fourth line defines the center location for each of the stars (or
  zero if that region is not going to be used).  It is set by fgs or
  guide.  The fifth line describes the OT tracking parameters which are
  explained in detail below.  The sixth line does the same for the
  telescope guide parameters.

Usual sorts of CCD control commands:
------------------------------------

  fnumber N  - set the running file number to N

  fprefix xx - set the file prefix to xx, i.e. output file will be xx.N

  sformat    - set the CCD readout format.  This can take 7 arguments
                 or otcom will prompt you for them if you do not
                 supply them.  The arguments are (in order) 

                    xbin ybin xoff yoff xsize ysize nbias

                 e.g.   sf 2 2 0 0 1024 1026 32

                 where the bin factors can be 1-N, the offsets are
                 measured in physical (not binned) pixels, and the
                 sizes and number of bias overclocks are in binned pixels.

  etime T    - set exposure time to T seconds

  filter (N) - request or set the filter to N (UH2.2-m and TFW only)

  go (N)     - do an exposure.  If N is present you get N identical
               exposures.  This can perform a large variety of
               actions depending on the "auto" parameters.  There are
               also piecemeal versions of go:

  clear (N)  - clear the CCD (N times)
  shutter A  - open/close the shutter if A is "open" or 1 / "close" or 0
  expose     - open shutter (if auto permits), wait, and close shutter
  rc         - read out CCD (and write files if auto permits)
  wf         - write files (according to auto)

  auto       - set up the automatic actions to be undertaken with "go"
                 This can take 7 arguments or otcom will prompt you for
                 them if you do not supply them.  The arguments are:

                 #wipe do_shut? readout? wr? do_OT? wr_OT? wr_vid?

                 #wipe    = number of clears before an exposure
                 do_shut? = 0/1 to open the shutter for an exposure
                 readout? = 0/1 to readout after the exposure completes
                 wr?      = 0/1 to write the image to a file after readout
                 do_OT?   = 0/1 to follow guide star(s) and do OT shifting
                 wr_OT?   = 0/1 to write the (all important) OT data file
                 wr_vid?  = 0/1 to write the 3D FITS file of the GS video

               some examples will make this clearer:

               normal snapshot       auto 1 1 1 1 0 0 0

               bias or dark frame    auto 1 0 1 1 0 0 0
                 (depending on whether etime=0 or etime>0)

               focus frame           auto 0 1 0 0 0 0 0
                 (would be preceded with clear, and followed with an
                  auto 1 1 1 1 0 0 0 and an "rc" or an 
                  auto 0 0 0 1 0 0 0 and a "go")

               OT tracking image     auto 1 1 1 1 1 1 1

               *LONG* OT image       auto 1 1 1 1 1 1 0

               exercise CCD          auto 1 1 1 0 0 0 0
                 (maybe while looking at signals with an oscilloscope)

  tel cmd    - do a telescope command.  There are a variety of commands
               available for a given telescope.  You can probably count
               on the following ones:

  tel roff E N                      = do an offset from the current 
                                      position of E and N arcsec
  tel xyoff dx dy                   = offset dx,dy unbinned pixels
  tel xyoff xfrom yfrom xto yto     = offset to-from, unbinned pixels
  tel xyoff xfrom yfrom xto yto bin = offset (to-from)*bin

  tel afocus F                      = set the telescope focus to F
  tel dfocus D                      = change the telescope focus by D

               Note that the "tel xyoff" command depends on otcom knowing 
               the orientation of the CCD; see the gparams command below.

               At the UH2.2-m there is a large variety of commands
                 which are probably already familiar to users of tcdcom

               At WIYN there are three other commands:

  tel info                          = dump out the telescope's idea of things
  tel filter N                      = set the filter to F (note that
                                      this currently uses N=0-7 for
                                      WIYN filters 1-8, sorry) 
  tel exptime T                     = set the WIYN shutter exposure to T
                                      this is overridden by "et" if
                                      T>4 sec, and et>4 sec, but defines 
                                      the actual exposure for 1<T<4 sec.

Guiding commands:
-----------------

  sgformat   - set the guide box parameters.  This can take 6 arguments
                 or otcom will prompt you for them if you do not
                 supply them.  The arguments are (in order) 

                    xbin ybin xoff yoff xsize ysize

                 e.g.   sg 2 2 1 1 16 16

                 where the bin factors can be 1-N, the offsets are
                 measured in physical (not binned) pixels, and the
                 sizes and number of bias overclocks are in binned pixels.

               The important part of this is the bin factor and box size,
               the offset simply is where the guide patches are temporarily
               lodged before readout.  FGS is how the actual locations
               of the guide stars is specified (or the "guide" command).

  gtime M    - set guide exposure time to M msec.  The actual exposure
               time will be a bit longer because the time the host
               spends analyzing the guide images adds to the
               integration time, and the overhead time of readout
               contributes to the net frame time.

  fgs (T)    - takes a quick exposure of T (default 2) sec of the
               four lower regions, pops up a display window, and
               expects you to make a selection in each of regions of
               no guide star "e" or a guide star "x", in order 0l, 1l, 2l, 3l.

  guide par  - set the guide locations by hand.  In this case there
               are 8 parameters, the x y locations of guide stars for
               each lower region, in pixel coordinates of the current
               binning.  The coordinates are what you would report if
               you had just taken a snapshot and not changed the
               readout parameters yet.  Use 0 0 to indicate a region 
               where there is no guide star present.  This is seldom used.

               A more common usage is if guide gets two arguments,
               which are interpreted as x and y offsets in pixels to
               be applied to existing guide star locations.  This is
               useful for dithering, e.g.  

                    tel xyoff 50 50
                    guide     50 50

               Note that although both are in pixels, the sense is
               deliberately opposite: dx and dy move the telescope in
               the +dx and +dy direction, whereas the guide star
               positions are offset by -dx and -dy.
 
               A final usage is "guide prev" which simply restores
               guide positions which have been previously set with an
               FGS or guide command.  A runaway guide star could be
               returned this way.

  tparams    - set up the OT tracking parameters with 6 arguments or
               otcom will prompt you for each.  The arguments are:

                 tpar alg wait gain max region_use exponent bias

               e.g. tpar 10 5 1.0 8 13331111 -1.0 1

                 alg   = decimal coded number of various prediction
                         parameters -- see Manual_algorithm for details
                         and read the description in Manual_track_predictions
                         on how the predictions are done.

                 wait  = number of guide iterations to wait before
                         applying OT shifts to the science regions.
                         This can be set to a large number (50000) to
                         use only telescope guiding and no OT tracking.

                 gain  = fraction of indicated shift to apply

                 max   = maximum offset permitted a box to follow a
                         guide star (pixels)

                 region_use:  8 digits for the regions in order:
                                   0l 0u 1l 1u 2l 2u 3l 3u
                         1 = (T) do OT tracking
                         2 = (G) use for a guide star
                         3 = (Q) leave quiescent, no OT tracking,
                                 telescope guiding only
                         4 = (P) push-away, steadily clock charge into
                                 the scupper to overcome a horrible
                                 bright defect or star.

                         Note that uses of 1 and 2 get set and reset by fgs.

                 exponent = exponent for how multiple guide stars
                            contribute to the shifts applied to
                            different regions.  The default of 
                            -1.0 means "use the closest guide star".
                            A positive exponent means weight the
                            different GS by inverse distance to the
                            exponent power.
                 bias  = 0/1 to do bias subtraction on the GS video frames

  gparams    - set up the telescope guide parameters with 6 arguments
               or otcom will prompt you for each.  The arguments are:

                 gpar on? rmin tmin gain PA EccwN?

               e.g. gpar 1 2.0 2.5 0.5 180 0

                 on?   = 0/1 to turn on telescope guiding, i.e. a
                         low-pass filtered error signal from the guide
                         stars making offset requests of the telescope

                 rmin  = minimum distance (pix) to trigger a guide request

                 tmin  = minimum time (sec) between guide requests

                 gain  = fraction of indicated offset to request

                 PA    = position angle on the sky of the top of the CCD

                 EccwN?= 0/1 parity, 0 for E CW of N, 1 for E CCW of N

                Note that the last two parameters must be set properly
                if you are going to use the "tel xyoff" command,
                regardless of whether you are doing telescope guiding.

Generally helpful commands:
---------------------------

  help       - list all commands with a very brief description

  quit       - quit otcom, ask whether the current state should be saved
  Quit       - quit otcom, without saving the state

  ls (arg)   - list files

  cd D       - change directory to D

  set        - set or unset a few internal variables:
  unset          clobber = overwrite files of the same name silently
               noclobber = ask if a file is going to be overwritten
                   short = write signed short FITS files with BZERO=32768
                unsigned = write unsigned short FITS files with BZERO=0

  ! cmd      - execute (and wait for) a shell command

  # anything - comment

Save and restore the state of otcom:
------------------------------------

  save (F)   - save the current setup (to file F)
  restore (F)- restore saved setup parameters (to file F)

Interrupt an exposure:
----------------------

  interrupt  - interrupt an ongoing exposure (just type "interrupt"
               and a newline).  The shutter will be closed and the
               exposure paused.  A "clear" will reset the exposure.

  resume     - resume an interrupted exposure where it left off.

Macro (script) facility:
------------------------

  call F (args)  execute a script of commands in file F with the
                 specified arguments 

Otcom has a simple but fairly powerful macro facility.  It is
invoked as "call macro_file" where the path of "macro_file" is
determined by the environment variable SRCPATH
(".:/usr/local/inst/script" by default) or the current directory.
Script files can call other script files to a very deep level.
Arguments can be provided to script files as white space separated
tokens.  Within the script tokens of the form $n are replaced with
these argument strings.  Only one pass is made of substitution.  The
argument $0 is the name of the script file itself, argument $1 is the
first argument, etc.  For example:

  call hoser this is a test

within the script hoser, the following replacements would be made:

  $0 = hoser
  $1 = this
  $2 = is
  $3 = a
  $4 = test

and if hoser had a line like

  call bingo $4 $0

the script bingo would have the following substitutions made:

  $0 = bingo
  $1 = test
  $2 = hoser

It is important for many commands that arguments be present (for
example if "sf" had too few arguments in a script it would go into a
mode of prompting standard input for answers and hang).  The script
facility therefore permits default settings for arguments so that a
user cannot get into trouble by calling a script without the right
number of arguments.  If the first line of a script starts "DEFAULT:",
the following tokens are taken to be defaults for the ensuing
arguments.  For example, this is a good start to an script to take a
focus frame which steps the focus and telescope through a range:

     DEFAULT: 5000 20
     # Args are $1 = focus start 
     #          $2 = focus increment
     #
     tel afoc $1
     et 2
     auto 0 1 0 0 0 0 0 
     sf 2 2 0 0 1024 1026 32
     clear
     go
     tel dfoc $2
     tel xyoff 0 50

There are some scripts in /usr/local/inst/script which will offer
some examples.  If an error is encountered during the execution of a
script, the entire input sequence is aborted and otcom returns to the
command line prompt.