Using "ccdcom" - MDM's CCD Control Program

Contents

• CCD Setup and Initialization
  • DSP Initialization
  • Utility Board
• Taking Exposures
  • Setup the Type of Image to Take
  • Set Exposure Time & Readout Format
  • Set Object and File Names
  • Miscellaneous Exposure Commands
  • Take an Exposure
  • Exposure-related commands
• ccdcom macro files (scripts)
• Commanding the TCS and MIS
• Operating System Commands
• FITS Headers
  • Time Specification Important Note!
  • Telescope Information
  • MIS Information
• Alternative Readout Modes
  • Drift Scanning
  • Shutterless Video
• Diagnostics [for staff use]

Introduction

MDM's facility CCD cameras are controlled using Leach GenI controller electronics, operated from Sun Sparcstations using the ccdcom package. When ccdcom is started up it will initialize communications with the parallel interface, allocate memory into which to read CCD images, and read enough from the DSP memory to get an idea of the status of the DSP code. ccdcom will try to determine whether the DSP is running the default code from ROM (which will not work for any of our CCD's), and will inform you if you should download appropriate code. ccdcom also initializes itself for CCD readout size and binning parameters from the numbers it reads from the DSP, so ccdcom can be terminated and then restarted without disturbing the DSP.

Currently five facility CCD cameras at MDM are operated using ccdcom:

1. echelle: SITe 2048x2048 (silver dewar)
2. templeton: SITe 1024x1024 (blue dewar*)
3. wilbur: Loral 2048x2048 (gold dewar)
4. charlotte: Tektronix 1024x1024 (blue dewar*)
5. nellie: STIS 2048x2048 (purple dewar)

ccdcom recognizes a number of commands. Any unique abbreviation will work, and ccdcom will prompt you if you enter an ambiguous command. When you first start ccdcom you should be aware of two self explanatory commands:

help <> Help

"help" lists the currently recognized commands. Angle brackets indicate arguments, and square brackets indicate optional arguments. "?" is an alias for "help".

quit <> Quit

"quit" terminates ccdcom. Ctrl+D will also do this.

CCD Setup & Initialization

After power-up or a hardware reset of the CCD electronics, you will need to initialize the DSP processor in the Leach electronics because its cold-reset state does not know how to readout any of the MDM CCD cameras.

To initialized the DSPs for your CCD, you need to read in a file of compiled DSP code and then download it to the DSP. This must be done each time the power is cycled or the DSP box is reset. Note, however, that you do not need to re-load code to the DSP if you exit and re-start ccdcom, since the DSP runs independently. If the power to the box been turned on or cycled, you will also need to initialize the utility board to start the temperature regulation (see the utility board commands below).

df <file> Read and download DSP code

"df" is a combination of ll and dl. It will fill in a ".lod" extension if it is missing, and it will look in directories according to the environment variable LODPATH, which can be set to a list of directories separated by colons. Thus, the visitor account has been provided with:

   setenv LODPATH .:./mydspcode:/opt/local/pkg/ccd/dsp

Examples:

   df wilbur    (Current DSP code for Wilbur) 
   df charlotte (Current DSP code for Charlotte)
   df nellie    (Current DSP code for Nellie) 

ll <file> Read DSP code .lod file

"ll" reads a DSP code binary file into the Sparcstation memory.
Examples:

   ll /opt/local/pkg/ccd/dsp/wilbur.lod 
   ll /opt/local/pkg/ccd/dsp/charlotte.lod 

Note: the DSP assembler code in a .asm file is compiled by the a56 compiler into binary code stored in a .lod file. For example,

   a56 mdm2048

will read and compile the asm file "mdm2048.asm" and write the lod file "mdm2048.lod".

Observers will never have to compile .lod files, they are already pre-compiled and ready to go.

dl <> Download DSP code

"dl" sends the DSP code to the DSP electronics, and then causes the DSP to start executing this code. "dl" also asks the DSP to recalibrate its A/D converter, which takes about 2 seconds.

safe <> Toggle Observing "safe mode"

The "safe" command will lock out the ccdcom "df", "ll", and "dl" commands during observing, preventing you from accidentally reloading the DSP code (wiping out any CCD format settings you have made using the sf command, like windowing or binning for the spectrograph) by typing "df" in the ccdcom window when you are trying to check the amount of free disk space with the Unix df command.

If you type "df", "dl", or "ll" during "safe mode", it will remind you that these commands have been locked out. To disable safe mode so you can use the ccdcom "df" command (and company) to reset the CCD, just type "safe" (or equivalently, "unset safe" or "set nosafe") and the commands above will be available.

The default mode is safe mode disabled. This command is new since version 1.26 of ccdcom.

An example of a typical startup session with the CCD named templeton would be:

   df templeton
   util init
   safe

Utility Board

The Leach utility board is used to regulate the CCD temperature. In order to use it, you must download DSP code which will talk to the utility board (currently wilbur, charlotte, and nellie). The commands provided in ccdcom for using the utility board are all of the form

   utility xxx

utility init <> Initialize utility board

You must execute this once if the power in the electronics box has been cycled. The utility board is largely independent of the rest of the Leach electronics, so downloading new code to run the CCD will generally not disturb the utility board.

utility [status] Display status of utility board

This command tells you the power supply voltages, the CCD temperature, and the status of the heater which regulates the CCD temperature. You might see a display like:

   Utility board status: 
    +40 V at +40.1           CCD temp at  -89.9     Elapsed time    0.000
    +15 V at +15.3       CCD set temp at  -89.9   Requested time    6.000
    -15 V at -15.0   Electronics temp at  +37.4
     +5 V at  +4.87       Heater percentage  24   Heater rate   0x1000

The CCD temperature is -90 C, and the heater is maintaining it there by application of 24% of its maximum voltage (6% of its maximum power of 4 W). The temperature inside the electronics box is 37 C. We do not use the utility board for exposure timing, so that part of the display is not useful.

utility tset <temp> Set desired regulation temperature

You can change the temperature where the heater will turn on to keep the CCD warm, but we trim the heat path between the CCD and LN₂ so even with no heating at all the temperature will not fall far below -100 C (if that). "utility init" sets the regulation temperature at -95 C because that is cold enough to make dark current negligible but warm enough for good CCD performance.

utility hrate <rate> Set the rate at which the heater voltage changes

The utility board algorithm adjusts the heater voltage according to the difference between actual and desired temperature. The rate at which it changes its voltage is proportional to "rate", which you may enter (in hex). A value of 0x10000 makes a very fast response which may oscillate for Charlotte; a value of 0x1000 (used by utility init) is much slower and seems to be stable. Observer's should leave this setting alone unless specifically instructed to change it.

Taking Exposures

1. Clear the chip
2. Open the shutter and wait for a predetermined exposure time
3. Close the shutter
4. Read out the CCD into memory
5. Write the contents of memory into a FITS format data file
6. Put the CCD into idle mode

First, the commands which tailor the sequence that will be executed by the next go command are given. Not all of these steps may be taken by a particular command, and the actual sequence executed depends on how the "automatic actions" are set, as described below.

There are a number of ways to set the parameters which govern what ccdcom does. Six commands are available which can be used to set integration time, object name, object type (a FITS header item), and default automatic actions. None of these does anything more than setting parameters to be used later.

Setup the Type of Image to Take

There are six commands that define the type of image to be acquired:

1. object: an astronomical object (direct image or spectrum)
2. flat: flat-field calibration image
3. bias: zero-second bias calibration image
4. dark: dark count calibration image
5. focus: focus-field exposure
6. comp: comparison arc calibration spectrum

object <[time [name]]> Setup for object

"object" prepares ccdcom to take an exposure of a general target. You can specify integration time as the first argument and an object name as the second. "object" also sets the automatic actions:

   #wipe Shutter Readout 
     1     on      on

Examples:

   object 300 N3031     (set integration time to 300 sec
                         and object name to N3031)

   object 0.18          (set integration time to 0.18 sec
                         and keep the object name unchanged)

   object               (set image type to object, leaving
                         integration time and name unchanged)

flat <[time [name]]> Setup for flat

"flat" prepares ccdcom to take a flat field exposure. You can specify integration time as the first argument and an object name as the second. "flat" also sets the automatic actions:

   #wipe Shutter Readout 
     1     on      on

Another command useful in conjunction with taking flats is istat.

bias <[time [name]]> Setup for bias

"bias" prepares ccdcom to take a bias frame exposure. "bias" ignores its first argument, but you can specify an object name as the second. "bias" also sets the automatic actions:

   #wipe Shutter Readout 
     1     off     on

NOTE: "bias" sets the exposure time to 0.0 seconds. If you follow a "bias" with an "object", "flat", "dark", etc. image, you need to remember to set the exposure time!

dark <[time [name]]> Setup for dark

"dark" prepares ccdcom to take a dark field exposure. You can specify an integration time as the first argument and an object name as the second. "dark" also sets the automatic actions:

   #wipe Shutter Readout 
     1     off     on

focus <[time [name]]> Setup for a focus frame

"focus" prepares ccdcom to take a focus frame exposure. You can specify integration time as the first argument and an object name as the second. The focus mode is useful for taking focus plates: each time the go command is issued, the chip is exposed but not read out. Thus multiple offset exposures can be taken at different focus values. When the desired number of exposures has been taken, use the rc command to read the chip and write to disk. "focus" sets the automatic actions:

   #wipe Shutter Readout 
     0     on      off

The procedure for a sequence of focus images of 10sec each is thus

    focus 10 beginning focus
    [first telescope focus setting...]
    go
    [second focus setting, offset telescope...]
    go
    ...
    [last focus setting, offset telescope a bigger step to mark it]
    go
    rc

A single image will be readout with the N separate focus images.

comp <[time [name]]> Setup for comparison

"comp" prepares ccdcom to take a comparison arc for a spectrograph. You can specify integration time as the first argument and an object name as the second. Unlike the five other image setup commands, "comp" keeps its own exposure time exposure and name separately from the others. If "comp" is issued without arguments, the exposure time and object name are set to the previous values defined by the last full "comp" command. This allows one to switch easily between taking object and comparison images without having to re-specify the exposure time and name. "comp" sets the automatic actions:

   #wipe Shutter Readout 
     1     on      on

Examples:

   comp 1.0 Hg-Ne    (set integration time to 1.0 sec and the object
                      name to Hg-Ne)
   comp              (set integration time and name to last comp values)

name <objname> Set a temporary object name

"name" is used to set a temporary object name which will be written into the FITS header of the next image(s) written, leaving all other exposure parameters (image type and exposure time) fixed.

"name" is a potentially confusing command. It only changes the object name loaded next into the image header, irrespective of the names that are associated with each of the six image types (object, flat, comp, bias, dark, and focus). If you use "name", the next commands can only be "et" (or "ep") to set the exposure time, and go to start an exposure. If you follow "name" with any of the image type commands above, the object name set by "name" will be deleted and substituted with the object name associated with that image type. Confusing? Yes. If you don't like this, try not to use "name".

auto <> Set automatic action

"auto" goes through the choices for the automatic actions, and prompts you to set each of the parameters, showing the current settings in [ ]'s. If you want to keep the current settings unchanged, just hit the <Enter> key at the prompt.

The automatic actions are:

#wipe n: Number of times to wipe the chip before starting the exposure.

Shutter on/off: Controls whether the shutter should be opened for the exposure.

Readout on/off: Controls whether the chip should be read out at the end of the exposure.

Write on/off: Controls whether a FITS file should be written after the chip is read out.

idle on/off: If on, at the end of a readout the chip is placed in a continuous wipe, or idle, mode.

Note how the automatic actions are used. For example, when you are taking a focus frame you will open the shutter many times on a given field, so the chip cannot be wiped before each exposure. The exposure must open the shutter, but must not read out the CCD upon termination. Thus, you need to be able to wipe the chip independently, and read out the CCD independently.

Set Exposure Time & Readout Format

These commands are used to set the exposure time and the CCD readout format (binning, overscan, and subregions).

et <seconds> Set exposure time

"et" sets the exposure time. Any floating point value is accepted; the accuracy of the exposure timing is somewhat better than 0.01 second, but it is ultimately limited by the mechanics of the shutter. "et" uses Unix to compute the exposure time, and an exposure which is based on Unix timing can be interrupted.

ep <seconds> Set precise exposure time

"ep" sets a "precise" exposure time. Any floating point value is accepted, and although "ep" is extremely accurate, note that the shutter takes about 10 msec to open or close, so the center of the chip enjoys about 20 msec longer exposure than the edges. "ep" works by putting the DSP to sleep for the specified time, so an exposure based on "ep" cannot be interrupted. Precise exposures can only be made in multiples of 0.01 second. REMEMBER to use the "et" command when finished with taking precise exposures, otherwise you may not be able to interrupt a future exposure when you want to.

In general, "ep" is rarely used.

sf <> Set format of CCD readout

"sf" permits you to change the format of the CCD readout, setting binning, starting pixels, number of pixels, and number of overscan columns. The command syntax is:

   sf binx biny skipx skipy readx ready overscan

If you type "sf" without arguments, you will be prompted for each of the 7 inputs.

NOTE: "sf" uses the convention that locations are specified in terms of unbinned pixels, and numbers of pixels to be read are specified in terms of binned pixels. Examples (for a 2048x2048 CCD):

   sf 1 1 0 0 2048 2048 32     - read full, unbinned 2048x2048 + 32 bias
   sf 2 2 0 0 1024 1024 32     - read full, binned 2x2 + 32 bias
   sf 1 1 512 512 1024 1024 32 - read 1024x1024 subimage centered on the CCD
   sf 4 4 1024 1024 256 256 32 - read upper right quadrant of 
                                 the CCD binned 4x4 pixels

Set Object and File Names

ccdcom creates filenames of the form:

    prefix###.fits

    prefix = text string prefix (e.g., ccd, bias., 20001214, etc.)
    ### = 3-digit running file number assigned by ccdcom, starting
          with 001
    .fits = FITS file extension ("suffix"), which identifies the 
            file format to IRAF, XVista, etc.

    prefix.###.fits

Each of the three elements of the ccdcom FITS filename is set by the commands below:

fp <prefix> Set file prefix

"fp" sets the prefix of the output FITS filename. The default ccdcom file prefix is "ccd.".

If you want filenames of the form

    foo.###.fits

with a dot (.) separating the prefix from the file counter, use

    fp foo.

noting the "." at the end. Otherwise, filenames of the form

    goo###.fits

are created by using

    fp goo

with no "." at the end.

Note that if you have to quit ccdcom and restart it, the file prefix is reset to "ccd." automatically. Beware!

fn <fileno> Set running file number

"fn" sets the value of the 3-digit running file number to be assigned to the next image written to disk. All subsequent images will count up from the value set by "fn".

ccdcom uses the current file number as a prompt ("###>"), and automatically increments the file number as each file is written.

Important!
If you quit and then restart ccdcom, it will reset its internal file counter to "001", which could overwrite earlier images. You will need to reset the file counter to the correct sequence number using "fn" (and also "fp" if required) before taking new data.

fits <> Toggle adding the .fits extension to filenames

FITS files must have the .fits extension or IRAF will fail to recognize them. The "fits" option will toggle whether the .fits suffix will be appended to filenames or not. By default, .fits is appended. You have to explicitly turn it off.

Miscellaneous Exposure Commands

status <> Show status

"status" shows the current parameters. For example:

   Frame: 002   File prefix: 'ccd.'   File suffix: '.fits'
   Format:  origin (0,0), size (2048,2048), binned 1x1, 32 bias
   Object name: 'Beginning Bias'  type BIAS
   Exposure: Set  0.00, Total int.  0.00 (Unix)
   Autowipe:  1, shutter off, readout  on, write  on, idle off

This shows that the next image (if you were to type go next) will be a bias image named "Beginning Bias" which will be written to a file named "ccd.002.fits".

comment <comment> Set comment for the FITS header

"comment" is used to add a comment line to the FITS header of the data files written by ccdcom after then next go or wf command.

iraf <> Toggle IRAF format for FITS file

IRAF (among others) is finicky about dealing with 16-bit FITS images, but the dynamic range and A/D converters for our CCDs are such that we want to save all 16 bits. The "iraf" option causes ccdcom to scale all FITS images to pack 16-bits of unsigned data (so-called "ushort") into standard FITS signed 16-bit integers ("short" or BITPIX=16 FITS format).

Specifically, this the FITS header parameter BZERO is set to 32768, and the image is written as a FITS-standard 16-bit integer data file. IRAF et al. use the value of BZERO in the FITS header to restore the pixel values to those provided by the camera.

By contrast, the old "not IRAF" format images stored pixel data as unsigned 16-bit integers, resulting in a non-standard FITS format image (a "ushort" image in IRAF parlance) that most FITS readers cannot read without special handling.

By default, "IRAF" format is assumed so that no additional processing will be required to display/analyze raw ccdcom images with IRAF, XVista, or whatever. You must explicitly issue the "iraf" command to switch back to the old format. We do not suggest this unless you have very good reasons for writing your data as non-standard unsigned integers.

NOTE: This is a change from previous versions of ccdcom. As of 2000 July 15 the default is IRAF format.

sound <> Toggle fancy sounds

The low-level routine called in SunOS versions of ccdcom has no equivalent in Solaris, so this function has been disabled in v1.27 and later of ccdcom.

Take an Exposure

When you are ready to begin an exposure, issue the "go" command:

go <[num]> Start exposure

Depending on the image type you have set, "go" will wipe the chip, open the shutter and close it a predetermined time later, read out the CCD into memory, write the data to disk, and set the CCD into idle mode, ready for the next exposure.

An exposure which has been started with "go" and Unix timing (et) may be interrupted by typing "Ctrl+C". This will close the shutter and return you to the ccdcom command level. You can then alter any parameters while the exposure is paused. For example, you can

• alter the exposure time with "et"

• change the eventual output file name with "fp" or "fn"

You can also resume the exposure (or not) in a number of ways:

• To resume the exposure, type "go"

• To read the CCD out now and end the exposure, type "rc"

• To abort the exposure and discard the image, type "clear"

Finally, you can take multiple exposures with the same parameters by issuing the "go" command with the optional num argument. For example:

   go 5

will take five exposures with the current parameters one after another.

Exposure-related commands

rc <[Xnx Xny]> readout the CCD

"rc" reads out the CCD, and if the auto-write flag is set, "rc" will write the resulting image to a disk file.

wf <[file]> Write FITS file

ccdcom reads out the CCD into memory, and maintains the image there. The "wf" command creates a FITS header for the image and writes it to a disk file. If the write fails (for example because the disk is full) "wf" will abort, but ccdcom will keep the data in memory and you can save your data after rectifying the problem that prevented the write.

istat <> Compute some useful statistics on the last CCD frame

Once an exposure is and the data written to disk, it is sometimes handy to compute some quick statistics on the data. This is especially useful for monitoring signal levels in twilight flats. The "istat" command computes the mean, rms deviation, and quartile values for the data section of last image read out from the CCD.

Note that istat works on the current image stored in the camera memory; it does not work on previous images that have long since been written to disk.

set <mode_name>

unset <mode_name> Set or unset a ccdcom flag

The flags controlled by set/unset are:

   clobber/noclobber

The "clobber" and "noclobber" mode names set or unset the "clobber" flag, which prevents ccdcom from overwriting an existing file,

   fits/nofits

which sets whether or not the .fits suffix is added to output FITS files (e.g., as in the fits command),

   iraf/noiraf

sets whether or not files are written in the default FITS-standard integer format (short), or the old-style non-standard FITS unsigned integer (ushort) format (e.g., as done by the iraf command

   safe/nosafe

which sets or unsets the observing safe mode.

Examples:

   set noclobber - don't overwrite existing files [default]
   unset clobber - same
   set clobber   - silently trash existing files
  
   set iraf      - make standard FITS integer files [default]
   unset iraf    - make old-style unsigned FITS 
   
   set fits      - add .fits to all output images [default]
   unset fits    - suppress adding .fits (old-style)
   set nofits    - same

   unset safe    - disable observing safe mode [default]
   set nosafe    - same
   set safe      - enable observing safe mode

idle <> Put camera in idle & recalibrate

"idle" first requests the DSP cpu to recalibrate the A/D converter (which can drift slightly with temperature), and then starts an infinite loop of reading out the CCD and exercising the signal chain. Any command received by the DSP terminates the idle mode.

It is probably a good idea to recalibrate the A/D converter once per night, and to put the CCD into idle mode if you are not going to be using the CCD for several hours (e.g., issue "idle" before going to bed).

clear <[num]> Clear (wipe) CCD

"clear" flushes any charge existing in the CCD. The CCDs are quite good about not retaining residual images, but you can give "clear" an argument if you want to wipe it several times. For example, you might do multiple clears after badly saturating the CCD with a bright star or room lights.

sync <> "Ping" the DSP

sync "pings" the DSP by sending it data and asking it to send it back. This is useful to check to see whether the CCD is alive and receiving commands properly from ccdcom, or if the electronics may need a hardware reset.

shutter <open | close> Open or close the shutter.

Direct control of the shutter independent of the "go" command. One possible use is doing knife-edge focus with the slit on the Modular Spectrograph. You should rarely have to operate the shutter directly this way.

ccdcom macro files (scripts)

source <file [line]> Read and execute ccdcom commands from a file

You can create macro files containing ccdcom commands and execute them with the "source" command. If you specify a line number as well as a file name, the execution will start with that line and continue to the end. This can be handy if your source macro aborts because of a benign error (such as TCS not ready) and you want to resume where you left off.

A source file can invoke another source command, but source will not return to the original file when it finishes the second file (there is no way to "return" from the second source file). However, tail recursion does work (i.e. "source bingo" can have "source bingo" as its last line, creating an infinite loop which you interrupt with Ctrl+C as usual.

A common use of "source" is to create one-line source files containing the sf command to setup a particular CCD format. For example, you might have two source files, one named "small" to set a 1024x1024 subregion in the middle of a 2048x2048 CCD:

    sf 1 1 512 512 1024 1024 32

and another named "full" to restore the full-frame readout:

    sf 1 1 0 0 2048 2048 32

You would then type

    source small

to set the CCD to the subframe readout, and

    source full

to restore full-frame readout.

The telescope command explained below is helpful in making useful macros. Note that ccdcom reads and executes the source file line by line, so don't change the file while ccdcom is executing it!

Commanding the TCS and MIS

   telescope <[command [args]]>

telescope

Request current status from the TCS and MIS, and print them out. This is a good way to check that ccdcom is communicating with the xtcs and xmis programs. If not, you could end up with FITS headers with no telescope pointing or filter information.

telescope sleep <n>

Go to sleep for n seconds. This is useful for macros which need to pause while some external TCS or MIS command completes.

Remote TCS Commands [MDM 2.4m Only]

telescope 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.

telescope 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.

Remote MIS Commands

telescope lamp <n state>

Turn off or on lamp n (if xmis is running). If n = -1 all lamps are extinguished; n = 0/1/2/3/4 for the flat/Ne/Ar/Hg-Ne/Xe lamps, and state = 0/1 corresponds to off/on. This is identical to hitting the appropriate button on xmis.

telescope finder <state> [MDM 2.4m Only]

Move the find/guide mirror of the MIS to guide/find position if state = 0/1, corresponding to out/in. This is identical to hitting the appropriate button on xmis.

Note: At the 1.3m, the remote finder mirror control is broken, and operated by a manual toggle switch in the control room.

telescope filter <n>

Select filter n on the instrument filter wheel. Here n can take values of 0-7 for the MIS filter wheel on the 1.3m and 2.4m telescopes, and 1-12 if using the MDM4K filter wheel on the 1.3m. This function is identical to hitting the appropriate filter button on the xmis tool. If no filter wheel is installed on the MIS, this command has no effect (though it will generate an error if executed as part of a script).

telescope gxy <x y>

Move the guide probe to position (x,y). This is identical to using the fields in xmis, and uses the same scale factor for the units.

telescope gdxy <dx dy>

Move the guide probe by an offset (dx,dy). This is identical to using the fields in xmis, and uses the same scale factor for the units.

Operating System Commands

ls <options> The usual Unix shell command.

Raw FITS files are written into the current directory by default, so that an "ls" from within ccdcom will list your image files.

cd <dir> Change directory.

"cd" changes the current working directory of ccdcom. This has the effect of changing the directory into which raw images written.

! <command>

Execute a shell command from within ccdcom.

FITS Headers

The following is a sample FITS header produced by ccdcom:

SIMPLE  =                    T  / STANDARD FITS
BITPIX  =                   16  / BITS/PIXEL
NAXIS   =                    2  / NUMBER OF AXES
NAXIS1  =                 1056  / NUMBER OF COLUMNS
NAXIS2  =                 1024  / NUMBER OF ROWS
BSCALE  =        1.0000000E+00  / PHYSICAL = BSCALE * DATA + BZERO
BZERO   =               32768.
DATE    = '2006-02-13'          / UT Date of file creation (CCYY-MM-DD)
ORIGIN  = 'ccdcom v1.31.2'      / FITS file creator
OBSERVAT= 'MDM     '            / Observatory Site
LATITUDE=              31.9500  / Latitude (degrees N)
LONGITUD=            -111.6150  / Longitude (degrees E)
TELESCOP= '2.4m Hiltner'        / Telescope used for observation
INSTRUME= 'Direct + Echelle CCD'  / Instrument used for observation
FRAME   =                    1  / Frame number of observation
CCDPICNO=                    1  / Frame number of observation
OBJECT  = 'test    '            / Name of object
IMAGETYP= 'OBJECT  '            / Type of observation
EXPTIME =                1.001  / Integration time (seconds)
DARKTIME=                4.102  / Dark current time (seconds)
TIMESYS = 'UTC     '            / Time System
DATE-OBS= '2006-02-13'          / UTC Date of observation (CCYY-MM-DD)
TIME-OBS= ' 21:59:49.00'        / UTC at start of exposure
JD      =       2453780.416539
RA      = ' 00:09:23.68'        / Telescope RA at Equinox
DEC     = ' 31:56:09.64'        / Telescope Dec at Equinox
EQUINOX =             2006.112  / Equinox of RA and DEC
HA      = '-00:00:51.95'        / Hour angle at start
ST      = ' 00:08:31.72'        / Sidereal time at start
ZD      = ' 00:11:03.22'        / Zenith distance (degrees)
AIRMASS =                1.000  / Airmass at start
FILTPOS =                    7  / Filter Wheel Position
FILTER  = 'GG420   '            / Filter ID
GPROBE  = ' 13067.00   4000.00'  / MIS Guide probe X Y
COMPLAMP= 'Flat     Hg-Ne  '    / MIS Lamps illuminated
GAIN    =                2.700  / Nominal gain (e-/ADU)
CCDBIN1 =                    1  / On-chip column binning (fast dir)
CCDBIN2 =                    1  / On-chip row binning (slow dir)
ROTANGLE=                 1.01  / Rotation angle (deg)
TELFOCUS=                  861  / Telescope focus
GPROBE  = '  4337.00   3647.00'  / Guide probe X Y
DATASEC = '[1:1024,1:1024]'     / Image area of frame
CCDSEC  = '[801:1824,513:1536]'  / Image area relative to full chip
BIASSEC = '[1025:1056,1:1023]'  / Overscan area of frame
END

Time Specification

We follow the IAU standards for denoting time in the headers as ISO-8601 format date and time specifications. The relevant header keywords are:

   TIMESYS = 'UTC     '            / Time System
   DATE-OBS= '2006-02-13'          / UTC Date of observation (CCYY-MM-DD)
   TIME-OBS= ' 21:59:49.00'        / UTC at start of exposure
   JD      =       2453780.416539

Important Notes about Times!

Between August 2005 and February 2006, the DATE-OBS keyword was erroneously recording the time of FITS file creation due to a bug in ccdcom. This was fixed on 2006 Feb 13 to actually report the true start-of-exposure time. The offset between the header recorded time and the true start-of-exposure for pre-2006-Feb-13 images is the combination of the exposure time and the CCD readout time. It should be possible to reconstruct the absolute start times to within 5-10 seconds in most cases, but the relative timing of observations is preserved to within 1-2 seconds.

Prior to August 2005, the UT keyword was recording the time at the start of exposure setup, which means before erasing the CCD. This can take up to 13-15 seconds on large (2Kx2K) CCDs, and so introduces a small offset in the time recorded in all pre-2005-Aug data.

Telescope Information

Before each image, the TCS is queried to get basic pointing information, stored as the following keywords:

   RA      = ' 00:09:23.68'        / Telescope RA at Equinox
   DEC     = ' 31:56:09.64'        / Telescope Dec at Equinox
   EQUINOX =             2006.112  / Equinox of RA and DEC
   HA      = '-00:00:51.95'        / Hour angle at start
   ST      = ' 00:08:31.72'        / Sidereal time at start
   ZD      = ' 00:11:03.22'        / Zenith distance (degrees)
   AIRMASS =                1.000  / Airmass at start
   ROTANGLE=                 1.01  / Rotation angle (deg)
   TELFOCUS=                  861  / Telescope focus

At the 2.4m, the TCS only reports RA, DEC, EQUINOX, ROTANGLE, and TELFOCUS. All of the other quantities (HA, ST, ZD, and AIRMASS) are computed from the time and position info. At the 1.3m, the header will store only a placeholder for ROTANGLE.

Instrument Information

The relevant instrument configuration info for your setup is stored as the following keywords:

   FILTPOS =                    7  / Filter Wheel Position
   FILTER  = 'GG420   '            / Filter ID
   GPROBE  = ' 13067.00   4000.00'  / MIS Guide probe X Y
   COMPLAMP= 'Flat     Hg-Ne  '    / MIS Lamps illuminated

GPROBE records the X,Y position of the guide probe (if used). Units are device encoder units. This could help you recover a particular guide star on later observations.

COMPLAMP lists the MIS spectral comparison lamps that were illuminated at the time of the exposure. If no lamps were lit, this header card is omitted.

Alternative Readout Modes

WARNING:
Neither of these modes has been used much (if at all) since the departure of MIT from the MDM Consortium, and there is no guarantee that they will work with the Solaris port of ccdcom. In fact, nobody could remember how they worked before so we could not test them with the new version of ccdcom as of December 2000. We include them here for historical interest, but suggest you stay away from them unless very curious and willing to spend your own telescope time to test them out.

Drift Scanning

The DSP is such a flexible way of running a CCD that we are starting to implement new modes of use. It is currently possible to do drift scanning (TDI) with the Loral and STIS chips. Using this mode requires some care and a special configuration; you should contact an old ccdcom expert if you're interested (otherwise that knowledge is arcane and not current). The pertinent command is:

drift <> Execute a drift scan.

The shutter is opened, the requested number of rows is read out, and the shutter is closed. The appropriate drift delay must have been entered in advance. Note that while it is possible to interrupt this command with Ctrl+C, the DSP will refuse to communicate until the full scan is finished, and the shutter will remain open.

Shutterless Video

Another optional readout mode is "shutterless video". This is a means of getting a fast readout of a small patch of the chip without using the shutter. The way this works is to select a small area to read out, open the shutter, and

1. Stare at the sky for a short period (several tenths of a second)
2. Rapidly shift the readout patch down the chip to the serial register
3. Read out the patch as fast as possible
4. Shift a clean patch of chip into the observation area
5. Go to 1 and repeat...

This can lead to ghost images, because the patch loiters down near the serial register while it is being read out, and if there happens to be a bright star in the sky whose light falls on this spot it will create new charge in addition to the charge from the object you were staring at.

It is also possible to get ghost images if your star is located at a horizontal offset from the region which you selected to display. The reason for this is that ccdcom cannot clear the entire serial register and maintain high speed. Thus when ccdcom reads out its little patch it also loads up the serial register with an entire horizontal strip. If a bright star is found in that strip it will eventually show up in the image several frames later when it gets shifted to the amplifier. The quick way to make sure that you are not looking at a horizontal ghost is to move the star to the left across the chip and if no new image appears at the right of the display, you have the correct image. The sure way to ensure you are not looking at a ghost is to read out a complete image in the usual way and make sure that the star is found in the region you are reading out with shutterless video.

Operationally this mode has been used by some experts (e.g., the MIT astronomers who originally introduced ccdcom) for focusing and examining the state of collimation and how the seeing is distorting the wavefront. Nobody in recent memory has used this mode with success since the departure of MIT from the MDM consortium.

Shutterless video requires that you download appropriate DSP code, select an area to examine with sf, and then use the two video commands.

vexpose <seconds> Set exposure time

"vexpose" determines how long the stare lasts

video <[record]> Start video

"video" is interrupted in the usual way with Ctrl+C. It can take one argument, and it will pop up a display window showing what the chip is seeing. This display will be closed when video ends. If you give video an argument it will save the frames in memory (and automatically quit when memory is exhausted). This image can be saved as a 3-D FITS file in the usual way with "wf" (although this must be done explicitly). The routine videoplay can be used to replay such a file as a movie identical to the original video display.

The upper left window shows what the CCD is seeing. You may adjust the display of this using the "palette" button (lower center) which cycles through a rainbow palette, black and white, and inverse BW. The stretch for the display (values for threshold and saturation) is selected by the long, skinny, horizontal bar which stretches through the middle of the display. There are logarithmically spaced ticks and a colored bar which covers the range between threshold and saturation. You can change the threshold by clicking the left mouse button within the palette bar, and you change the saturation by clicking the right button within the bar.

The upper middle window is a display of the centroid of the current and previous frames. The most current points are white, the next most current points are bright green, and the oldest points are dark green.

The upper right window is an average of previous images. This is implemented as a leaky average (exponentially decreasing contribution from old frames), and you can reset the averaging ("Zero Ave") or change the leak time (exponential decay rate) by using the two buttons immediately below the window. (The left mouse button decreases and the right button increases the value of the leak time.) A leak time of zero (0) means average forever, until you restart the average with the zero average button. Under these two buttons is found the PSF button, which does a full-up Gaussian fit to the average image and displays the results within the button. The "Raw Leak" button lies on the bottom right, and when clicked it toggles to "Ctr Leak". The action of this is to center each incoming raw image before adding it to the leak.

The lower left window is a FWHM bar graph. The purple ledger lines represent units of CCD pixels (perhaps binned), and the pinkish lines represent arcseconds (if ccdcom is providing the information). You may increase or decrease the number of ledger lines by clicking with the right or left buttons within the graph.

Each incoming frame has its FWHM displayed as a tiny green dot in the FWHM display. Occasionally there is a small, vertical red line drawn which is the FWHM of the leaky image on the right. The vertical extent of the red line shows the major and minor axes of the leaky image, and the rate at which the red lines appear is determined by the leak time. If you click on the PSF button under the leaky average window to get a full-up Gaussian fit to the average image, the resulting FWHM will be shown as a yellow line in the FWHM display. Over on the lower right is a button labeled "Raw FWHM", which can be toggled to "Ave FWHM". This changes the FWHM display to one which has been smoothed by a Gaussian whose FWHM is approximately the leak time.

The display window can exert a little bit of control over ccdcom and the ccd readout. In the lower center are two buttons labeled "Bin:" and "Time:". If you click the mouse on these (left to decrease, right to increase) you can change the CCD binning factor (by one per click) and integration time (by 0.05 sec per click). Since ccdcom is extremely busy, the communication from the display back to ccdcom is quite slow and you need to be patient (click-ahead works, though). There is currently no way to change the origin or size of the readout; video must be killed with Ctrl+C and the "sf" command used.

Lastly, the bottom line shows some information: frame number, frames lost (not harmful), time between frames (larger than exposure time from readout overhead), FWHM of the current image (in pixels), RMS of the centroid motion shown in the center window (in pixels), sky value, and maximum brightness in the current frame (in ADU).

In order to use shutterless video, you will usually go through the following steps:

1. Load in the video DSP code ("df vwilbur" for Wilbur, "df vcharlotte" for Charlotte, "df vnellie"for Nellie).

2. Select the area you want to examine in the usual way with "sf".

   We recommend that you restrict yourself to 64x64 because the time to read out more pixels degrades the quality of the video. It is also a good idea to use a small value for the X-axis origin, because the charge can be shifted out more rapidly. If you want a large field to locate stars, use a binning factor of 6x6; if you want to focus, use a binning factor of 1x1. Generally speaking, you should take the trouble at the start of a run to learn where the default video area lies in the finder so you can acquire a star with no hunting around.

3. Select an exposure time. A star which is bright enough in the finder to cause vertical bleeding will need about 0.5 seconds (the default).

4. Using the finder select a good star, ideally bright enough to cause vertical bleeding, and ideally the brightest star around to avoid the possibility of confusing ghosts. Shift the star over to where your video patch lies on the chip.

5. Remove the finder mirror and start up video. If the star is not there you may have to hunt for it a bit with the hand paddle. If you still can't find it you may have to go to a coarser binning factor to see a larger patch of sky. Remember that you have a real time display, and you can move the telescope, change the focus, change the filters, collimate the telescope and see the effect right away.

6. Interrupt the video with Ctrl+C.

Important!

DON'T FORGET to download wilbur.lod (or charlotte.lod, etc.) to resume conventional observing!

Diagnostics [for staff use]

diag rm <M:addr[-addr]> Read DSP mem

"rm" reads the P:, X:, or Y: memory of the DSP chip. All in hex (alas?).

diag wm <M:Xaddr Xval> Write DSP mem

"wm" writes values to the P:, X:, or Y: memory of the DSP chip. Also in hex (also alas?).

diag ii <> Re-init I/O

"ii" reinitializes the I/O with the parallel interface card. It closes and then re-opens the /dev/s16d0 device, effectively re-setting the default communications level between ccdcom and the s16d parallel I/O card. It has no effect on the CCD camera or the fiber-optics interface box.

diag ic <> Initialize camera communications

"ic" initializes communications with the CCD camera by sending an "RST" to the timing board and then resynchronizing communications with the DSPs. This has the effect of destroying any downloaded DSP code and replacing it with the basic monitor program which has code for a different CCD. You will have to reload the current CCD's DSP code after issuing an "ic" command.

diag di <> Initailize the Fiber-Optics Interface

"di" sends a device initialization pulse to the fiber-optics interface. Largely unused.

diag oc <cmd> Issue a command to the DSP interpreter

"oc" sends a three letter mnemonic command to the DSP cpu. Most of the useful commands are sent by various ccdcom commands automatically, but some commands can only be sent via "oc".

Example:

   oc HGN        (set DSP to high gain = 1.94 e/adu [default])
   oc LGN        (set DSP to low gain = 3.85 e/adu.
                  Note that this will probably not be satisfactory
                  because the bias level will probably drop below
                  zero.  You would need to use a different .lod
                  file [e.g. lowgain.lod] and download it to adjust
                  both the gain and bias level.)

diag db <level> Set debug level

"db" sets the level of diagnostic messages for ccdcom to print. Useful values are 0, 1, and 2. They are as follows:

    0 = no debug information [default]
    1 = basic debug printing on CCD and file I/O.
    2 = very verbose debug output, especially during CCD readout,
        used primarily to debug the s16d readout code.
    

diag L1 <cnt [{r|c} data]> - 4MHz loopback test mode.

Test fiber optic interface in hardware loopback mode. Receiver is wired for operation at 4MHz, and a fiber is connected directly between the receiver and transmitter. This test runs cnt loops of 65536 words each, with values 0 through 0xFFFF. If the "c" option is specified, then data is a value (in hex) to be sent repeatedly. If the "r" option is specified, then data is used as a seed for a random number generator and 65536 words of random data are sent per loop.

diag L3 <cnt [{r|c} data]> - Timing board loopback test

Loopback test with timing board in place. Must have code downloaded or be in cold reset state. Similar to L1 in other respects.

diag L5 <cnt [{r|c} data> - Timing board loopback test: high 16

Same as L3, but tests high 16 bits of data word. Must have code downloaded that supports the THI command (e.g. mdm2048.asm)

diag pe - Toggle error printing for DIAG commands.

Toggles printing more verbose error messages for DIAG commands, usually for debugging purposes. The default error printing mode is OFF.

When encountering error codes in ccdcom, such as

-3 and -4 do the following.

For a -3 error code, go to the ccd controller box

At the ccd camera and press the hardware reset button.

For an error code of -4 you have to turn off

the gold power supply, the one with the

instructions on the bottom, for about 30 to 40

seconds then turn the power supply box back on.

It is wise to exit ccdcom and re-enter when error code is

encountered.

ccd_aread: timed out  *** Error encountered in asynchronous read: data suspect
Failed, return code = 4227072, elapsed = 141.04
This is not really a problem. Another go of the ccd can be done and should readout fine.