TCS commands for the MDM8K Camera

2006 October 24

The detcom software that runs the MDM8K data taking system has been modified to talk to the 2.4m and 1.3m TCS systems (xtcs). This document describes what you need to do to setup detcom so that you will get TCS information into your MDM8K FITS headers. For 2.4-m observers, it also describes new remote commands for setting the secondary mirror focus and commanding offsets from the detcom command prompt.

Startup

The MDM8K camera talks to the xtcs program: xtcs. This program needs to be started on the observer's console (hiltner at the 2.4m, mcgraw at the 1.3m) before the MDM8K camera can get any info from the telescope controller.

You can start xtcs on the observer's console in one of two ways:

Using the mouse, select "xtcs" from the "Telescope Control" menu (left mouse click on the desktop).
From the Unix command prompt by typing
```
    xtcs &
```
in an xterm window.

After starting xtcs, go to the detcom command window (or open it if you haven't already), and enter the command:

   tcs on

to initialize the TCS link.

To verify that the TCS link is working, type

   tcs status

This should retrieve and print the current TCS information on the detcom command window after a short (1 sec or so) delay.

NOTE: If you need to restart xtcs for any reason during the night, you will need to type the "tcs on" command again in detcom to re-establish the link.

Also note that xtcs and detcom may be started in any order since you have to initialize the TCS link by hand within detcom anyway.

TCS information in the MDM8K FITS Headers

Before an exposure starts (after cleaning the CCD but before the shutter is opened), detcom will query the TCS to get the current pointing information. It will also query the system clock to get the time and date. Immediately thereafter (the delay is millisec), the shutter will be opened. This means that all of the TCS information written into the headers refers to the start of the observation. Comments attached to each FITS header card should say this explicitly.

The system clock is kept synchronized as well as possible with network time services (we use a special program called xntpd that calibrates the internet link delay time). Tests with GPS receivers shows that absolute times delivered by the system are good to about the nearest second. Because the clock is read immediately before the shutter is opened, the offset should be effectively zero. Your mileage may vary, of course.

The information returned by the TCS and placed into the FITS headers of each image are as follows:

   DATE-OBS= '2002-07-10'         / UTC Start of observation
   TIME-OBS= '03:11:04.00'        / UTC Time at start of observation
   JD      =        2452465.63269 / JD at start of observation
   LST-OBS = '14:56:06.55'        / Sidereal time at start of observation
   OBSTYPE = 'OBJECT '            / Observation/ Exposure type
   EXPTYPE = 'OBJECT '            / OBSTYPE is the new name for this
   EXPNUM  =                    2 / Exposure Sequence Number
   OBSID   =                    2 / Observation Sequence Number
   EXPTIME =               3.0000 / Integration time (seconds)
   DARKTIME=               3.0000 / Dark current time (seconds)
   TCSSTAT = 'Enabled'            / TCS link status
   TELESCOP= 'MDM 2.4m'           / MDM 2.4m Hiltner Telescope
   LATITUDE=             31.95000 / Latitude (degrees N)
   LONGITUD=            -111.6167 / Longitude (degrees E)
   EQUINOX =              2002.52 / Equinox of RA and DEC
   RA      = '14:56:09.17'        / Right Ascenion
   DEC     = '+31:56:06.59'       / Declination
   HA      = '-00:00:02.62'       / Hour Angle
   SECZ    =                1.000 / Airmass at start of exposure
   TELFOCUS=                 3904 / Telescope focus encoder readout
   ROTANGLE=               2.9000 / Teescope rotator angle

The header info for the 1.3m is the same, except for the TELESCOP card, and the TELFOCUS and ROTANGLE keywords are omitted (since they are not available on the 1.3m TCS).

Note that there are two other date/time cards in the header, DATE and MSTTIME, these refer to the time that the image header was written, and make no reference to the observation itself. This is consistent with standard FITS usage as practiced by programs like IRAF et al.

Troubleshooting

The easiest way to test if the TCS link is active is to type:

   tcs status

in the detcom command window. If all is well, you will receive a printed summary of the current TCS info on the detcom screen. If not, you have some options.

If the TCS link is dropped (or you forgot to start it), you will be warned in the detcom window when it tries to query the TCS before an exposure starts. Once the exposure starts, you have no choice but to ride things out and wait until it has been readout to disk before starting the TCS link with "tcs on".

While telescope information (RA, Dec, etc.) will not be in the header of an image taken while the TCS link is down, you will get accurate timing information (DATE-OBS, TIME-OBS, and JD keywords) for all images regardless of the TCS link status. If after the fact you are wondering what is going on, look at the TCSSTAT keyword in the header. It should read either Enabled or Disabled depending on the TCS link status.

Remote Telescope Commands

The basic syntax for TCS commands in detcom:

   tcs <[command [args]]>

These commands work on both the 1.3m and 2.4m telescopes:

   tcs on      - initialize the TCS link
   tcs off     - disable the TCS link
   tcs status  - get and print TCS status

These commands only work at the 2.4m telescope:

   tcs offset dra ddec  - offset the telescope from current position
   tcs focus foc        - set the secondary to absolute focus "foc"
   tcs focus +dfoc      - step the secondary focus by +dfoc
   tcs focus -dfoc      - step the secondary focus by -dfoc
   tcs sleep nsec       - sleep for nsec seconds

These commands may be used either interactively or in detcom command scripts. Details are as follows:

tcs on

Initialize the TCS link between detcom and xtcs.

tcs off

Turn the TCS link off. This is mostly here for completeness.

tcs status

Request current status from the TCS and print them on the detcom command window. This is a good way to verify that detcom is communicating properly with the xtcs program. If not, you could end up with FITS headers with no telescope pointing information.

The 2.4m TCS offers additional commands for offsetting the telescope or setting the telescope focus:

tcs offset <dE dN> [MDM 2.4m Only]

Offset the telescope by dE arcseconds east and dN arcseconds north. Note that this command will return after the TCS accepts and initiates the request, so there may be a delay between when ccdcom is ready to execute a new command and when the telescope completes its offset. This command communicates with xtcs and only works on the 2.4-m telescope.

Examples:

   tcs offset -300.0 0.0

Send the telescope 300 arcsec (5 arcmin) West of its current position.

   tcs offset 0.0 30.0

Send the telescope 30 arcsec North of its current position.

   tcs offset 30.0 -60.0

Send the telescope 30 arcsec East and 60 arcsec South of its current position.

The time required to complete an offset depends on the size of the offset and the direction (E/W offsets are slower than N/S offsets). When using tcs offset it will return immediately before the move has completed, but it will also warn you to watch the TCS PC screen to know when the move has finished. If used in a detcom command script, you will need to use the tcs sleep command to insert the necessary pause between successive commands.

tcs focus <####> [MDM 2.4m Only]

Focus the telescope by moving the secondary mirror to absolute encoder position <####>. If <####> is preceeded by a +/- sign it will move the mirror <####> steps relative to the current mirror position.

Examples:

   tcs focus 3900

Sets the secondary mirror to absolute focus position 3900.

   tcs focus +30

Advance the secondary mirror focus +30 steps from its current position.

   tcs focus -10

Back the secondary mirror focus off -10 steps from its current position.

As with tcs offset, the detcom command prompt will return before the requested focus setting has been completed. detcom will remind you to watch the TCS PC screen to know when the your focus motion has been completed so you can issue another detcom command. If using this command in a script, you will need to use the tcs sleep command to insert the necessary pause before executing another detcom command.

tcs sleep <nsec> [MDM 2.4m Only]

Go to sleep for nsec seconds.

Telescope offset and focus motions need time to complete, but the TCS response immediately to the request, returning you to the detcom command prompt before the motion has even started in some cases. As such, if using either tcs offset or tcs focus in a detcom command script, you will need to insert a few "sleep" intervals in between command so, for example, you don't take an image before the telescope has stopped moving to a new offset position.

Example:

   tcs focus +10
   tcs sleep 10
   go

This steps the secondary mirror focus by +10 steps, sleeps for 10 seconds to allow it to complete, then takes an image.

NOTE: The exact sleep interval required depends on the size of the move requested, so you will need to experiment interactively to determine the right interval for your scripts. It is a good idea to add a buffer of 2-3 seconds over your estimate, since sometimes the TCS PC is slow to respond on roughly 1-2 sec timescales. This should avoid getting into a "race condition" between the TCS and detcom.

Updated: 2006 October 24 [rab/mdm]