DRAMA Interface to the TCS : TELD

Summary

TELD is a DRAMA task, taskname "TCS", which runs on the telescope control computers. It converts DRAMA actions into TCS commands which it passes to the TCS, the action returns any TCS error status on completion. It receives information from the TCS which it makes available as DRAMA parameters. It also writes FITS header files containing the telescope packet.

TCS commands

Here is a list of all DRAMA actions supported by TELD; a more detailed explanation of TCS commands and their use can be found in the relevant TCS user manual. Most DRAMA actions have the same syntax as the corresponding TCS command. Note that not all commands are available at all telescopes.

DRAMA actions with no timeout will complete when the TCS returns an acknowledgement status; if an error status is returned it is copied to the action's completion status. The completion status TCS__TIMEOUT indicates that TELD tried ten times to send the command to the TCS, and then gave up.

DRAMA actions with timeouts send TCS commands that move mechanisms and will usually complete when the mechanism has reached its demanded position (and is tracking reliably in the case of the telescope axes). The completion status TCS__LIMIT indicates that the mechanism reached some limit before it attained its demanded position. The completion status TCS__TIMEOUT indicates that the timeout period expired before the TCS had reported that the mechanism had reached its demanded position. 

ADD
If no parameter is given, writes the current contents of the edit source block as a new entry in the user catalogue.
If a parameter is given, writes the current telescope position as a named entry in the user catalogue (MARK command).
Format:  ADD [source-name
Parameters:  source name (string)
Timeout: None

AGPROBE
JKT specific command. Returns status of the autoguider probe movement, either COMPLETE or TIMEOUT.

APERTURE
Offset the telescope so that an image moves by a vector fixed in the focal plane.
Format:  APERTURE aperture-number
Parameters:  Aperture number (integer) in the range 0 - 20.  
Timeout: 5 minutes !!
Comments: Offsets corresponding to each aperture number must have been set up previously by using the ENTER or STORE command.

AUTOGUIDE
Lock or unlock the autoguider loop.
Format:  AUTOGUIDE state [x y [EW-gain NS-gain]]
Parameters:  state (string) {ON | OFF | SUSPEND | RESUME | CENTRE} 
x, y (double) desired pixel coordinates of guide star 
not used EW-gain, NS-gain (double) autoguider gains 
Timeout: 5 seconds
Comments: EW-gain, NS-gain are not used, but are accepted for compatibility with old scripts.

DFOCUS
Offset the focus to compensate for additional optical elements.
Format  DFOCUS focus-offset
Parameters:  focus offset (double) in mm 
Timeout: None

DOME
Move the dome to the specified azimuth and stop it.
Format:  DOME angle
Parameters:  angle (double) in degrees 
Timeout: 3 minutes

FOCOFF
Ancient history, was used by the Perkin-Elmer TCS at the INT and JKT, included for compatibility with old ICS code. Deprecated, use DFOCUS instead.

FOCUS
Drive the focus to a specified setting and stop it.
Format:  FOCUS setting
Parameters:  focus setting (double) in mm 
Timeout: 3 minutes

GOCAT
Retrieve the entry for the named source from the user or system catalogue and then send the telescope to track it.
Format:  GOCAT source-name
Parameters:  source-name (string of up to 20 characters) - it must be enclosed in double quotes if it contains any spaces 
Timeout: 5 minutes

NEXT
Sends the telescope to track the source whose data are in the edit source block
Format:  NEXT 
Parameters:  None 
Timeout: 5 minutes

OFFSET
To offset the telescope by a given amount.
Format:  OFFSET {ARC | TIME} delta-ra delta-dec
Parameters:  ARC - tangent plane offset; TIME - RA, Dec offset
delta-ra (double) in radians, range -0.1 to 0.1 radians
delta-dec (double) in radians, range -0.1 to 0.1 radians
Timeout: 30 seconds
Comments: The origin of a tangent plane offset is the nominal offset position, which is zero by default.

PARK
Causes the telescope to move to a defined park position and stop.
Format:  PARK [ZENITH | AP1]
Parameters:  ZENITH (default) - park telescope at zenith 
  AP1 - park telescope at Access Park 1
Timeout: 5 minutes

POINT
Log, in TPOINT format, the present position of the telescope as derived from the raw encoder readings.
Format:  POINT [OLD | NEW | CALIBRATE]
Parameters:  OLD (default) appends to the latest set of log files, unless none exist, in which case a new set of pointing files are opened in the POINTING directory.
NEW opens a new set of log files in the POINTING directory, and logs the telescope position.
CALIBRATE opens a new set of log files in the CALIBRATE directory, and logs the telescope position.
Timeout: None

PULLIN
Autoguide on specified pixel position, command returns when guide star is in position.
Format: PULLIN x y
Parameters:  x, y (double) pixel coordinates of guide star
Timeout: 3 minutes
Comments: Sends the TCS command AUTOGUIDE ON x y WAIT

ROTATOR
Causes the rotator to move to the specified position angle and stop.
Format:  ROTATOR {SKY | MOUNT} angle
  ROTATOR {FLOAT | VERTICAL | VFLOAT}
Parameters:  SKY - sky position angle
MOUNT - mount position angle
angle (double) in degrees 
Timeout: 5 minutes

SLOWOFF
Applies a tangent plane offset at the specified rate.
Format:  SLOWOFF delta-ra delta-dec rate [ABS | ADD]
Parameters:  delta-ra (double) in arcseconds 
delta-dec (double) in arcseconds 
rate (double) in arcseconds/second 
  ABS (default) - offset origin is the nominal offset position
  ADD - offset origin is the current offset position (ie. cumulative)
Timeout: 1 minute

SOURCE
Enters new source data into the edit source block.
Format:  SOURCE target-position
Parameters:  target-position (SDS structure of type target_t).
Timeout: None

TWEAK
Applies a given aperture offset.
Format:  TWEAK x-off y-off [rot-off]
Parameters:  x-off, y-off (double) aperture offset in arcseconds.
  rot-off (double) rotational offset in arcseconds
Timeout: 10 seconds

USER
Allows any TCS command to be sent as a parameter
Format:  USER command
Parameters:  command is any valid TCS command, including all required parameters. The command must be encased in double quotes if it consists of more than one word.
Timeout: None

Commands not supported by TELD can be entered as a parameter to the USER command; if there are any spaces in the command, the command must be enclosed in quotes. For example, the command STATION PRIME is sent as USER "STATION PRIME".

WARNING: If an unsupported command is missing a required parameter, the TCS will prompt for the parameter on its own USER interface and will not accept any more commands until either the parameter is given or CTRL-Z is typed to abort the command on the TCS USER interface.

TCS DRAMA parameters

TELD sets up the following DRAMA parameters:

Parameter Type Units Description
TELESCOPE String Telescope name, eg. INT 
LATITUDE double radians Geodetic latitude of telescope
LONGITUDE double radians Geodetic longitude of telescope
HEIGHT double metres Height above mean sea level
SCALE double radians/mm Plate scale
STATION String Focal station
INSTRU String Instrument
AUTOG String Autoguider
MESSAGE String TCS informational message
TUBE double degrees C Temperature of telescope tube
POSITION tcsTrack_t current state of telescope, etc
TARGET tcsTarget_t target parameters

tcsTrack_t and tcsTarget_t are defined in the file tcstypes.h, their definitions are reproduced here.

/* Structured type defining a target for the TCS: */
typedef struct { char name[21]; /* Name of object. */
double ra; /* Right Ascension (radians). */
double dec; /* Declination (radians). */
double diffRa; /* Diff. track, RA (radians/day). */
double diffDec; /* Diff. track, Dec (radians/day). */
double equinox; /* Equinox of position (years). */
double properRa; /* Proper motion, RA (radians/year). */
double properDec;/* Proper motion, Dec (radians/year).*/
double epoch; /* Epoch for proper motions (years). */
double parallax; /* Annual parallax (arcsec). */
double radVel; /* Radial velocity (km/s). */
char coordType;/* Coord. system ('B', 'J' or 'A'). */
} tcsTarget_t;
 

/* Structured type describing the telescope's current tracking: */
typedef struct { double mjd; /* Modified Julian date (days). */
double last; /* Local Apparent Sideral Time (rad).*/
double ra; /* RA being tracked (radians). */
double dec; /* Dec. being tracked (radians). */
double equinox; /* Equinox of position (years). */
char coordType; /* Coord. system ('B', 'J' or 'A'). */
double alt; /* Altitude of Telescope (radians). */
double altErr; /* Error in declination or altitude (radians). */
double az; /* Azimuth of telescope (radians). */
double azErr; /* Error in hour angle or azimuth (radians). */
double rot; /* Position angle of rotator (rad). */
double roterr; /* Error in rotator position. */
double parallactic;/* Parallactic angle (radians). */
double focus; /* Telescope focus (mm). */
double actFocus; /* Actual telescope focus (mm). */
double azDome; /* Azimuth of dome aperture (rad). */
double airMass; /* Air mass (dimensionless). */
double xApNom; /* Nominal Aperture X */
double yApNom; /* Nominal Aperture Y */
double xApOff; /* Aperture offset in x (rad). */
double yApOff; /* Aperture offset in y (rad). */
double raOff; /* Positional offset in RA (rad). */
double decOff; /* Positional offset in Dec. (rad). */
double skyPa; /* Rotator sky-position-angle (rad). */
char rotMode; /* Code for rotator mode. */
double guideX; /* Guiding point in x (A/G pixels). */
double guideY; /* Guiding point in y (A/G pixels). */
char guiMode; /* Guiding mode. */
double telTemp; /* Telescope temperature */
double focTmpCorr; /* Focus temperature correction (mm) */
double focAltCorr; /* Focus elevation correction (mm) */
double focFltCorr; /* Focus correction for filter (mm) */
int vignette; /* True when beam is vignetted. */
char telstat[21];/* Tracking/moving status */
} tcsTrack_t;

TARGET is updated by the TCS when the telescope is sent to a new target, POSITION is updated every second, the other parameters are updated when they change. POSITION.telstat can take the values GUIDING, TRACKING, MOVING, STOPPED, LIMIT or ENGMODE.

Telescope packet

On receipt of an ARCHIVE_B command (at the beginning of an exposure), TELD will save relevant data. On receipt of an ARCHIVE_E command (at the end of an exposure), TELD will write the telescope packet file to the OCS. This is described in the document INS-DAS-22. The contents of the tcs packet are described in INS-DAS-26.


TCS Software Manager
Last modified: 10 January 2006