Hexapod-Control Software (tkhex)

This page is still under construction.

This is an early release of this software. Expect a few problems.

The current version of this manual is located at http://ccd.ifa.hawaii.edu/hexapod/.

This web-page is a reference page for the new hexapod user interface, tkhex. This is not a tutorial. For a tutorial, you should see:

• Using the new Autoguider
• The UH 88-inch Tip-Tilt system
• Using the Tip-Tilt System

Contents

1. Introduction
2. Tkhex User's Reference
   1. Basic Operation
   2. Advanced Operation
   3. For Experts Only
3. The Hexapod TCL Interface
   1. Definitions and Notation
   2. Compiling
   3. TCL Interface Commands
   4. To Do

Tkhex User's Reference

If you run multiple versions of tkhex simultaneously, only one must be active at any time. You should not even read the current value of the hexapod, while another interface is active. Also, the displayed values are not automatically updated when another tkhex moves the hexapod.

Basic operation

The Focusing Window

If the system is properly collimated, you will only need to adjust the focus. The system will adjust the collimation parameters automatically.

To adjust the focus automatically:

• Adjust focus by 5 or 10 microns
• Press "Send" or enter a Carriage Return

If you collimate manually, do not use the Focus window. Using the Focus window will undo any manual collimation.

Advanced operation

The Collimation Window

The optical coordinate system describes the orientation and position of the secondary mirror by specifying the location of an image on the detector (NS and EW location), by the focus position (Focus), and the amount of Coma of the image (NS and EW Coma).

In order to focus and collimate manually:

• 

If you collimate manually, do not use the Focus window. Using the Focus window will undo any manual collimation.

Sign Conventions

-	-	Positive	Negative
Coma	NS	Increase North	Increase South
	EW	Increase East	Increase West
Location	NS	Move image North	Move image South
	EW	Move image West	Move image East

The Physical-Coordinates Window

This coordinate system describes the orientation and position of the secondary mirror by specifying the location of the center of the mirror (NS and EW translation and focus) and the tip and tilt of the mirror (NS and EW tilt)

To adjust the Physical coordinates:

• 

If you adjust the physical coordinates manually, do not use the Focus window. Using the Focus window will undo any manual collimation.

Sign Conventions

-	-	Positive	Negative
TRANS	NS	Move image North	Move image South
	EW	Move PI South	Move PI North
TILT	NS	Move image North	Move image South
	EW	Move PI West	Move PI East

The Log Window

For Experts Only

Setting the Daemon Host

To set the daemon host:

• 

Seeing the Auto-Collimation Parameters

Viewing and Setting the Leg Lengths

This can be very dangerous, unless you know exactly what you are doing!

This coordinate system describes the orientation and position of the secondary mirror by specifying the lengths of the six legs of the hexapod (in microns) or by specifying the lengths of the six legs of the hexapod (in encoder units), relative to a standard reference length.

To set the leg lengths:

• 

Make sure that you know exactly what you are doing before using this window!

Note: Increasing the encoder offsets decreases the separation between the ends of the hexapod. (This may be wrong. I'm not sure about this anymore!)

If you adjust the leg lengths manually, do not use the Focus window. Using the Focus window will undo any manual collimation.

The Hexapod TCL Interface

Definitions and Notation

In any commands which are described in this document, any words which are written using lower-case letters are keywords, and must be typed exactly as shown. Any words which are written in all-caps are dummy-parameters.

Most of the Tcl commands require a Tcl array or arrays as parameters. "ARRAY" may be replaced by any Tcl array.

The hexapod position can be described using several different coordinate systems.

Focus + autocollimation (Pickles)

The user specifies only the focus position, and lets the software figure out the best collimation parameters.

Variable	Units	Description
$ARRAY(focus)	microns	Secondary Mirror translation (Focusing direction)

The Optical parameters

The user adjusts parameters which affect the location and coma of an image on the detector. This is probably the most convenient way to focus and collimate the telescope.

Variable	Units	Description
$ARRAY(nsloc)	arcsec	Location (North-South)
$ARRAY(ewloc)	arcsec	Location (East-West)
$ARRAY(nscoma)	microns	Coma (North-South)
$ARRAY(ewcoma)	microns	Coma (East-West)
$ARRAY(focus)	microns	Secondary Mirror translation (Focusing direction)
$ARRAY(rotation)	arcsec	Secondary Mirror rotation (Normally 0)

The Physical Parameters

The user specifies the position of the secondary mirror directly, by specifying the location of the center of the mirror and by specifying the tip and tilt of the mirror. This is the most intuitive (though not the most convenient) way to describe the hexapod.

Variable	Units	Description
$ARRAY(nstilt)	arcsec	Secondary Mirror tilt (North-South)
$ARRAY(ewtilt)	arcsec	Secondary Mirror tilt (East-West)
$ARRAY(nstrans)	microns	Secondary Mirror translation (North-South)
$ARRAY(ewtrans)	microns	Secondary Mirror translation (East-West)
$ARRAY(focus)	microns	Secondary Mirror translation (Focusing direction)
$ARRAY(rotation)	arcsec	Secondary Mirror rotation (Normally 0)

The Encoder Values

This is the most primitive (and most dangerous) way to describe the hexapod. The Encoder values are specified directly.

Don't use this, unless you really know what you are doing. This provides no protection from mistakes, and can easily lock up the hexapod.

Variable	Units	Description
$ARRAY(0)	encoder units	Encoder 0
$ARRAY(1)	encoder units	Encoder 1
$ARRAY(2)	encoder units	Encoder 2
$ARRAY(3)	encoder units	Encoder 3
$ARRAY(4)	encoder units	Encoder 4
$ARRAY(5)	encoder units	Encoder 5

Compiling

In order to use these Tcl functions, you must build the subroutine library and link it with your program. To do this, you should read the instructions in the Makefile and then edit the Makefile. You should not need to change any other files. Then type 'make'.

If you have a Tcl program and you wish to include these functions, you need to call Hex_Init and link with libhex.a. This will define the hex_io and hex_calc Tcl commands.

TCL Interface Commands

The Hex_io Command

Hardware control.

connect

hex_io connect HOST

Make a connection to the daemon on the specified HOST. You must connect before you can send commands to the daemon.

disconnect

hex_io disconnect

Disconnect from the daemon.

send

hex_io send [-nowait] ARRAY physical

Given a Tcl array, move the hexapod to the specified location.

If -nowait is specified, then this command returns immediately. It returns an estimate, in seconds, of the time that this command will take to complete (with a little extra time thrown in, to account for network delays). Use hex_io wait to complete this command.

hex_io send [-nowait] ARRAY encoder

This command is very dangerous. If this command is used improperly, it can cause the hexapod to become locked in position. Recovery is very difficult, and cannot be done in software. Use
hex_io send ARRAY physical
instead.

If -nowait is specified, then this command returns immediately. It returns an estimate, in seconds, of the time that this command will take to complete (with a little extra time thrown in, to account for network delays). Use hex_io wait to complete this command.

wait

hex_io wait TIMEOUT

Wait for a hex_io send -nowait command to complete. If TIMEOUT is exceeded, returns an error.

read

hex_io read ARRAY encoder

This command reads back the encoder values from the hexapod-control hardware. To convert these values to more convenient coordinates, use the hex_calc convert command.

The Hexcalc Command

Utility functions.

convert

This command calculates the values of one set of coordinates, using a different set of coordinates.

Note: The input and output arrays may be identical.

hex_calc convert ARRAY autocoll ARRAY2 optical

hex_calc convert ARRAY optical ARRAY2 physical

hex_calc convert ARRAY physical ARRAY2 encoder

hex_calc convert ARRAY physical ARRAY2 optical

hex_calc convert ARRAY encoder ARRAY2 physical

validate

Takes the specified array, and makes sure that its values are reasonable.

hex_calc validate ARRAY autocoll

hex_calc validate ARRAY optical

hex_calc validate ARRAY physical

hex_calc validate ARRAY encoder

To Do

• Should be able to leave power supply on for successive commands.
• Should be better at handling multiple simultaneous users.