A remote Tcl interface to the Palomar Autoguider.

The Tcl interface to the autoguider is designed for use by users who want to control the autoguider from scripts or from custom programs that imbed the Tcl interpretter. It is contained in a dynamically loadable Tcl package. An example of a script that uses the tcl interface is the autoguider configuration tool.

Loading the guider package

The simplest way to load the autoguider package into a running Tcl interpretter is to enter the following Tcl command:

  source /guider/lib/autoguider.tcl.

This script loads the package into the program, establishes a connection to the autoguider, and defines a few extra utility procedures.

Alternatively, you can just load the autoguider package by entering:

 load /guider/lib/libautoguider.so

Starting an event loop

Object updates won't be received from the autoguider unless the Tcl event loop is running. If you use the Tcl/Tk window shell, wish, then you won't have to do anything special to ensure this. However, if you plan use the plain Tcl shell, tclsh, then you will have to explicitly activate an event loop. To do this, type:

  guider activate

If you are using tclsh interactively, then you should type this command before typing any autoguider commands.

  tclsh
  % source /guider/lib/autoguider.tcl
  % guider activate
  $ ...

The prompt will change to a $ sign, but you will be able to type into the shell just as before.

If you are using tclsh non-interactively to execute a Tcl script, then you should activate the event loop at the very end of the script, after setting up callbacks. No commands following the activation command will be executed until the connection to the autoguider is lost.

Listing objects

The autoguider package is basically just an interface to a distributed database of configuration objects. It is updates to these objects that control the behavior of the autoguider. The intricate details of all of the objects are listed in the software architecture page, in the section titled "The contents of the Autoguider database", and are described further in the description of the autoguider tasks. If, as recommeded above, you loaded the autoguider package by typing:

  source /guider/lib/autoguider.tcl

then a simpler listing can be obtained by typing:

  list_objects

This presents a long listing, so alternatively if you just want a reminder of what objects are available, type:

  guider list

This displays a list of object names. If you then wanted to know the names of the members of the Move object, then you could enter:

  guider list move

This would return/display the string

"north east
mrate"

. If you then wanted to know the type of the north member, you could enter:

  guider list move north

This would return/display the string "float".

Sending an updated object to the autoguider

To change an object in the autoguider database, use the

guider
set

command. For example, to initiate a telescope move of 3.5 arcseconds north by 2.4 arcseconds east, at a rate of 10 arcseconds per second, one could send an update of the Move object, like so:

  guider set move 3.5 2.4 10

The arguments that follow the move object name are those listed by the guider list move command.

Getting the current value of an object

To read the contents of an object from the autoguider database, use the guider get command. For example, to get the current value of the Move object, one could type:

  guider get move north east mrate

Where north, east and mrate are the names of the variables in which the contents of the object, in the order listed by the guider list move command, will be returned.

Establishing a callback

If you are writing non-interactive scripts, then you will want to register Tcl procedures to be called whenever updates of specified objects are received from the autoguider. To do this, first be sure that the event loop is running, then use the guider callback command to register procedures to given objects. For example, to asynchronously display updates of the Move object, one could type:

  proc show_move {} {
    guider get move north east mrate
    if {$mrate == 0} {
      puts "Move completed."
    } else {
      puts "Moving $north arcseconds north & $east arcseconds east"
    }
  }
  ...
  guider callback move show_move

The autoguider package would then invoke the show_move command every time that an update to the Move object was received. Note that if updates of a given object occur at a higher frequency than can be passed to clients, then intermediate updates will be omitted.

The guider callback command returns/displays the previous callback command for the specified object. This enables one to temporarily override an existing callback, like:

  set old_callback [guider callback move show_move]
  ...
  guider callback move $old_callback

Selecting objects of interest

To reduce ethernet traffic, and the associated load on the autoguider, the autoguider only sends object updates to clients that have explicitly requested them. If you know in advance what objects you are going to be reading and/or providing callbacks for, then you should use the guider add command to select them. If you don't do this then the guider get command will incur the overhead of temporarily selecting the specified object, waiting for the autoguider to send its latest value, then deselecting it. Note that the guider callback command also quietly selects its target object if not already selected, but it then leaves the object selected. An example of selecting a set of objects of interest is:

  guider add move status guiding

This tells the autoguider to asynchronously send updates of the Move, Status and Guiding objects, whenever their values change. As its name suggests, the guider add command is cumulative. Each invokation adds to the list of selected objects.

However...

Note that updates of the Target and Star objects occur up to 30 times per second, so unless you need to provide permanent callbacks for them, I suggest that you don't leave them permanently selected. The following section shows one way to avoid this. If you don't need to establish callbacks for them, just use the guider get command without explicitly selecting them. This has some overhead, as described before, but compared to swamping the ethernet, this probably isn't so bad.

Losing interest

When your script no longer wants updates of a given object, it can deselect the object by using the guider remove command. For example, the following code shows how one could asynchronously wait for a good star solution and print its flux, then stop watching for further star-object updates.

  # Tell the package to call watch_star whenever the star object
  # is updated.

  guider callback star watch_star

  # Display the flux of the first usable star solution received.

  proc watch_star {} {
    guider get star flux usable north east

    # Do we have a good star solution?
    # If so, print its flux then stop watching for further updates.

    if {$usable} {
      puts "Flux = $flux"
      guider remove star
    }
  }

Note that the guider remove command has the side effect of removing any callback that is registered to the object.

Connecting to the guider

If the connection to the guider is lost for some reason, then to reconnect to the guider, use the guider host command. For example:

  guider host marla

If called without a host name, the guider host command returns the name of the current host. This will be blank if no connection has been established. For example:

  set host [guider host]
  if [string length $host] {
    puts "The current autoguider is $host"
  } else {
    puts "No connection has been established"
  }

If you want to disconnect from the autoguider, specify a blank name for the host, like:

  guider host ""

Watching for changes in connection status

If you want to be informed whenever a connection to the autoguider is established or lost, use the guider host_callback command to supply a procedure to be called. For example:

  proc host_changed {} {
    set host [guider host]
    if [string length $host] {
      puts "Autoguider connection established."
    } else {
      puts "The autoguider connection has been lost."
    }
  }
  ...
  guider host_callback host_changed

Shutting down the autoguider

If you want to shut down the autoguider, type:

  guider shutdown

Be warned that if you do this, restarting the autoguider will necessitate a trip to the computer room to either press the reset button, or to power cycle the autoguider VME crate.

Canned utilities:

If you used

  source /guider/lib/autoguider.tcl.

to load the autoguider package, then you will have access to the following Tcl procedures.

Convert from relative arcsecond units to relative pixel units.

Usage:
  arcsec_to_pixel north east dx dy

Input parameters:
  north - The northward offset to be converted (arcsec).
  east  - The eastward offset to be converted (arcsec).

Output parameters:
  dx - The name of the variable in which to record the
       corresponding X-axis camera-pixel offset.
  dy - The name of the variable in which to record the
       corresponding y-axis camera-pixel offset.

Convert from relative pixel units to relative arcsecond units.

Usage:
  pixel_to_arcsec dx dy north east

Input parameters:
  dx  - The X-axis pixel offset to be converted.
  dy  - The Y-axis pixel offset to be converted.

Output parameters:
  north - The name of the variable in which to record the
          corresponding northward sky offset (arcseconds).
  east  - The name of the variable in which to record the
          corresponding eastward sky offset (arcseconds).

Keep the target area at a given sky location while moving the telescope a given distance.

Usage:
  dither north east

Input parameters:
  north  -  The distance to move the telescope north (arcsec).
  east   -  The distance to move the telescope east (arcsec).

Move the telescope a given distance north and east.

Usage:
  move north east

Input parameters:
  north  -  The distance to move the telescope north (arcsec).
  east   -  The distance to move the telescope east (arcsec).

Produce a list of all autoguider objects and their contents.
```
Usage:
  list_objects
```
Activate the Tcl event loop.
```
Usage:
  activate
```

Martin Shepherd (mcs@astro.caltech.edu).