Agile ICC Manual

This manual describes the commands and replies for the Agile ICC.

The Agile ICC can be reached by telnet to nimble on port 1025.

Contents

• Commands
  • addCards
  • changeNumExp
  • expose
  • fSlideConfig
  • fwConfig
  • fwHome
  • fwMove
  • help
  • params
  • setPreclears
  • shutdown
  • status
  • Plus standard commands from TclActor
• Keywords
  • Exposure command arguments
    • bin
    • extSync
    • gain
    • overscan
    • readRate
    • window
  • Exposure metadata (output as an exposure sequence begins)
    • numCircBufImages
    • readoutTime
  • Status
    • ccdTemp
    • currFilter
    • expStatus
    • fwHomeDuration
    • fwMoveDuration
    • fwReply
    • fwStatus
    • gpsSynced
    • ntpStatus
  • Parameters
    • addCards
    • biasSecGap
    • ccdSetTemp
    • ccdTempLimits
    • defBin
    • defGain
    • defReadRate
    • defExtSync
    • defOverscan
    • fSlideConfig
    • fwConfigPath
    • fwCtrllrCommLog
    • fwNames
    • fwOffsets
    • fwSlotMinMax
    • maxOverscan
    • minExpTime
    • minExpOverheadTime
    • noFwConfig
    • noFwSlideConfig
    • preclears
  • Other
    • shutdown
    • Plus standard keywords from TclActor
• FITS Keywords
• Pixel Coordinates

Commands

Note:

• You must not put spaces around = (equals) or , (comma). The command parser is too primitive to handle it.
• AgileICC is not responsive to commands while it is busy connecting to the camera.
• Commands and keywords are not case sensitive, but values such as filename components are.

addCards name number

Add number dummy FITS header cards to each image. The cards will be named name0, name1...

The command will be rejected if these requirements are not met:

• 0 <= num <= 100 (use 0 for no dummy cards)
• length of longest dummy keyword (len(name) + len(num-1 as decimal)) <= 8

changeNumExp numExp

Change the number of exposures in the current exposure sequence. Special values for numExp are:

• 0: take an unlimited number of exposures
• -1 (or any negative number): stop after the current exposure is read out

(New in version 1.1)

expose type args

type must be one of abort, stop, object, flat, dark, bias. Two types are handled specially:

• abort: the exposure sequence is aborted as quickly as possible, discarding the current exposure. Additional arguments are entirely ignored.
• stop: the exposure sequence is halted after the current exposure is finished. The current exposure is saved. Additional arguments are entirely ignored. (New in version 1.1; formerly stop was a synonym for abort).

args consists of one or more of the following, separated by spaces:

• time=float: exposure time in seconds. Required for object; permitted for biases only if 0.
• n=int: number of exposures. 0 means no limit.
• name=string: image path and name prefix. This is the part of the image path before the sequence number.
• seq=int: sequence number of first image saved; defaults to 1
• places=int: number of digits in image sequence number; defaults to 5
• suffix=string: image name suffix, excluding .fits; defaults to no suffix

• gain=low/med/high: amplifier gain; defaults to med
• readrate=slow/fast: readout rate; defaults to fast
• extsync=yes/no: use external sync pulse?

• bin=int: bin factor (for both x and y); required if window or overscan specified, else defaults to 1
• window=xbeg,ybeg,xend,yend: window (aka subimage) in binned pixels. The end is included in the image. Defaults to the entire CCD. If you specify window then you must also specify bin. 1,1 is the lower left corner pixel. See pixel coordinates for more information.
• overscan=x,y: overscan, in binned pixels; defaults to defOverscan. If you specify overscan then you must also specify bin.
  Warnings:
  • We recommend y=0! Overscan in y corrupts the top overcan.y pixels of the data (one of the camera's many unpleasant quirks) and it is not clear that the y overscan pixels are useful for anything.
  • The first biasSecGap unbinned pixels of x overscan are not usable to measure bias and so are excluded from the bias section (BIASSEC in the FITS header). If you want a usable bias section then be sure to specify an x overscan larger than biasSecGap/bin.

Note that the minimum exposure time is the image readout time (plus a small bit of time of overhead), with a an absolute lower limit of 0.1 seconds. For short exposures you must use readrate=fast, bin=2 (or more), and you may also have to reduce the window size or reduce the overscan.

fSlideConfig [filterName,[focusOffset]]

Set or clear information about the filter in the filter slide. If no arguments are supplied then the configuration is cleared (filterName set to "?" and focusOffset set to NaN). If you supply a filter name then the focus offset defaults to 0.

See pixel coordinates for details on the bin, window and overscan arguments.

Warnings:

• You must specify "name" and specify it as an absolute path that the server has permission to write to. If you omit "name" then the files will be saved somewhere very odd.
• An exposure sequence will be rejected if it would overwrite an existing image.
• The ICC does not verify object vs. dark. It is your responsibility to open or close the eyelid.
• The ICC will disconnect and reconnect the camera after every exposure sequence. This is to avoid a known data corruption bug in the camera vendor's control software.

fwConfig path

Load a filterwheel configuration file. The default directory is /export/FILTERS and the default file name extension is .txt. The format is as follows:

• Leading and trailing whitespace is ignored
• Blank lines and lines beginning with # are ignored (after stripping leading and trailing whitespace)
• All other entries must be one of the following, or else the file is rejected (to avoid hiding spelling errors):
  • NFILTER 6 indicates that there are 6 filters. If the value is not 6 then the file is rejected.
  • FILTERslotNum name indicates the name of a filter. Filter names may contain spaces and some special characters, but please avoid invisible characters and backslash. If slot number is out of range [1, 6] then the file is rejected.
  • OFFSETslotNum num indicate filter offset (can be a float). If slot number is out of range [1, 6] then the file is rejected.

Note: these files are used by both SPIcam and Agile, but their requirements may differ:

• NFILTER is optional for Agile ICC (though if it is present then it must have value 6). However, SPIcam apparently requires it to be present and may require it to be the first data entry.
• Data entries are optional for Agile ICC; missing slots are set to name="empty slotNum" and offset=0.0. I don't know if SPIcam accepts missing entries.
• FILTER and OFFSET keywords do not have to be in order.

fwHome

Home the filterwheel

fwMove slot

Move the filterwheel to the specified slot. The valid range is specified by fwSlotMinMax.

help

Prints a summary of available commands.

params

Print system parameters, including the temperature set point, minimum exposure time and various defaults.

setPreclears preclears

Set the number of times the CCD is cleared before an exposure sequence starts. The value must be positive. The default is 5, which is the maximum number that seemed to make any difference based on our tests. However, preclears are quite fast, so feel free to ask for more if you want them.

Note that preclears occur only at the beginning of an exposure sequence, before the first exposure begins integrating; they do not occur before each exposure.

shutdown

Shut down the Agile ICC.

status

Read current status and print it out. Normally status is output as it changes, so this command is primarily used at connect time and for debugging.

Keywords

Note:

• Status keywords are output whenever the associated status changes, in reponse to a status command and possibly for other reasons. In addition, at least one keyword is reported once per minute for use as a heartbeat.

addCards=name, num

Dummy FITS header card info. See the addCards command for more information.

biasSecGap=int

The first biasSecGap unbinned pixels of x overscan are not useful for bias determination. They might be a mix of dark current and read noise, but we are not sure. See the overscan section of the expose command for more information.

bin=int

Binning factor. See also pixel coordinates.

ccdSetTemp=temp, state

CCD temperature setpoint, in C, and a summary state keyword. state is one of: normal, low, high. The normal setpoint is -40.0 C; a variation of more than 0.1 C is reported as low or high.

ccdTemp=temp, state

CCD temperature, in C, and a summary state keyword. state is one of: normal, low, high, veryLow, veryHigh,

ccdTempLimits=low, high, veryLow, veryHigh

Temperature error limits, in C, that control the corresponding ccdTemp state keyword. The sign is ignored. For example if ccdTemp - ccdSetTemp < |low| or |veryLow| then the ccdTemp state will be low or veryLow.

currFilter=slotNum, slotName, slidePos, slideName, focusOffset

Information about the current filter or filters:

• slotNum: filter wheel slot number, or ? if unknown
• slotName: name of filter at this slot, or "?" if unknown
• slidePos: position of filter slide; one of: In, Out, ?
• slideName: name of filter in filter slide; "" if slide is out, "?" if slide position is unknown
• focusOffset: focus offset for these filters (μm); 0.0 if unknown

defBin=int

THe default value of bin for the expose command.

defGain=readRate

THe default value of gain for the expose command.

defReadRate=gain

The default value of readRate for the expose command.

defExtSync=yes/no

The default value of extSync for the expose command.

defOverscan=x, y

Default value of overscan for the expose command. The value is chosen to give a usable bias region even for unbinned images.

expStatus=state, expType, expTime, currExpNum, numExpRequested, begTimestamp, totDuration, remDuration, imagePath

Exposure status. The fields are:

• state: one of:
  • idle: nothing is happening
  • flushing: the initial exposure of a sequence that uses extSync has unknown duration and so is discarded; flushing means that this exposure has not yet been read out
  • integrating: an exposure is integrating
  • expDone: an exposure finished and was saved as a FITS file
  • done: the exposure sequence ended normally
  • aborted: the exposure sequence was aborted by "expose stop"
  • failed: the exposure sequence failed
• expType: exposure type: one of object, bias
• expTime: requested exposure time, in seconds
• currExpNum: number of exposure being taken (starting from 1)
• numExpRequested: number of exposures requested
• begTimestamp: timestamp of start of this state (the current exposure if integrating); UTC (unless we switch Nimble's clock to TAI)
• totDuration: predicted total duration of current state (sec); nan if unknown
• remDuration: predicted remaining duration of current state (sec); nan if unknown
• imagePath: full path to image FITS file that has just been saved (if state=expDone) or will be saved (otherwise); "" if unknown

Note: the predicted duration does not include readout time. This will cause a delay between the time the exposure has ended and the image is available. Readout time of a full-frame unbinned image is 1.1 seconds with fast readRate, 10.8 seconds using slow readRate. Readout time is reported at the start of each exposure sequence using keyword readoutTime.

extSync=extSync

Use external sync pulse: yes or no

fSlideConfig=filterName, focusOffset

Configuration of filter slide (whether or not it happens to be installed). To see if the filter slide is installed see currFilter. The fSlideConfig fields are:

• filterName: name of filter in filter slide, or "?" if unknown
• focusOffset: focus offset (in μm), or NaN if unknown

fwConfigPath=path

Path to filterwheel configuration file; "" if no configuration file was loaded.

fwCtrllrCommLog=path

Path to filterwheel controller communications log file; "" if communications is not being logged.

fwHomeDuration=sec

Predicted duration of filterwheel home command (sec)

fwMoveDuration=sec

Predicted duration of filterwheel move command (sec)

fwNames=name1, name2...

Filter name in filter slot 1, 2.... A filter name may contain spaces and other special characters (but not invisible characters or \). A name is "?" if unknown.

fwOffsets=offset1, offset2...

Focus offset (in microns) for filter wheel slot 1, 2.... An offset is NaN if unknown.

fwReply=str

Reply from filterwheel controller. This will be seen when executing a nonstandard commmand that begins with "fw ".

fwSlotMinMax=min, max

Minimum and maximum slot number for fwMove command.

fwStatus=currSlot, desSlot, statusWord, estRemTime

Filter wheel status.

• currSlot: current slot; ? if unknown.
• desSlot: desired slot; ? if unknown.
• statusWord: status as a hexadecimal bit mask (0x...); see Status Word Bits in the Filterwheel Controller Manual for documentation of the bits. ? if unknown (e.g. the fw device is disconnected).
• estRemTime: Estimated time remaining for current command (in seconds); 0 if no command executing. NaN if unknown (e.g. the fw device is disconnected).

Note that the controller reports -1 for unknown slot number and AgileICC translates this to ?.

Sample output: fwStatus=5, 5, 0x00000000, 0.0

gain=gain

Amplifier gain; one of low, med or high

gpsSynced=F/T

Indicates whether the clock card is synchronized to the 1 PPS pulse from the GPS receiver. It must be synchronized if you need accurately timed images.

maxOverscan=int

The maximum allowed overscan in x and y, in binned pixels. A request for more overscan along either axis will be silently truncated.

minExpTime=sec

Minimum allowed exposure time. This value was chosen by experiment so that a long series of fast exposures should complete reliably without overloading any part of the system.

minExpOverheadTime=sec

Minimum gap between image readout time (as reported by the camera for the chosen size of image) and the requested exposure time. This limit is meant to increase the reliability of long sequences of short exposures. However, it has not been measured experimentally and if it causes a problem we may be able to reduce it.

ntpStatus=isRunning, server, stratum

Status of the NTP client:

• isRunning: T/F/? depending on whether the NTP client is running
• server: NTP server, or ? if unknown
• stratum: stratum of NTP server, or ? if unknown; a value >3 probably indicates a problem

The NTP client should be running to keep the ICC's system clock to within 1/4 second of true time. Otherwise images may have incorrect timing information.

numCircBufImages=numImages, maxImages

The number of images in the circular buffer and the maximum number allowed. If numImages steadily climbs and you are trying to take more than maxImages images then your sequence is likely to fail.

overscan=x, y

Amount of overscan, in binned pixels

noFwConfig

A warning that the filterwheel configuration is unknown.

noFwSlideConfig

A warning that the filter slide configuration is unknown.

preclears=int

The number of times the CCD is cleared before starting an exposure sequence.

readRate=readRate

Amplifier readout rate: slow or fast

readoutTime=sec

CCD readout time, in seconds.

window=begx, begy, endx, endy

Image window (subframe), in binned pixels. See also pixel coordinates.

shutdown

Indicates that the Agile ICC is shutting down.

version=str

Software version.

FITS Keywords

Notes on FITS keywords:

• UTCSTAMP is the time of the start of the exposure. If using the external sync pulse (as usual) then this comes from a timer card that is synchronized to the observatory's GPS clock. If not using the external sync pulse (e.g. all bias images) then this comes from the system clock. See EXTSYNC.
• EXTSYNC is T if using the external sync pulse to trigger exposures, F otherwise. All images except biases will typically be taken with EXTSYNC true. Bias images will always have EXTSYNC false.
• GAINNAME is the name of the gain code used (one of low, med or high)
• RDRTNAME is the name of the read rate used (one of slow or fast)
• READTIME image readout time, in seconds, as reported by the camera. Useful for comparing AVAILMIN/END to UTCSTAMP.
• AVAILMIN and AVAILMAX mark a window of time during which the camera finished reading out the image. This can be useful for sanity-checking the image timestamps. If all is well, the image should be available one read time (READTIME) after the exposure start time (UTCSTAMP). If there is a problem then you might see a jump in these values.

  AVAILMIN and AVAILMAX are both taken from the system clock (which is maintained by an ntp time client), whereas UTCTIMESTAMP derived from the accurate clock card (if using the external sync pulse), which is synched to a GPS receiver.

  It is a window rather than a single time because the ICC polls the camera to find out when an image is available from the camera. AVAILMAX is the time it realized the image was available and AVAILMIN is the previous time it checked for that image.

Pixel Coordinates

Agile ICC follows the APO 3.5m standard for instruments for pixel coordinates:

• Pixel coordinates start from 1,1 (following the FITS standard)
• All pixel coordinates are binned pixels. This is true both for commands and replies. To prevent surprising results from an exposure, you must always specify the bin factor if you specify window or overscan.
• x is along rows (serial register); y is along columns
• window includes the end pixel; thus a window of 1,1,100,100 is a 100x100 region.

Examples:

• The full 1024x1024 image at various bin factors:
  • bin=1 window=1,1,1024,1024
  • bin=2 window=1,1,512,512
  • bin=3 window=1,1,342,342
• A 100x100 region starting at the lower left-hand corner is window=1,1,100,100 for any bin factor small enough that 100x100 binned pixels are available.
• A 200x200 region from the center at various bin factors:
  • bin=1 window=413,413,612,612
  • bin=2 window=157,157,356,356
• The command expose ... bin=1 window=413,413,612,612 overscan=10,5 will result in an image that is 210x205 pixels (including overscan).

Agile ICC was written by Russell Owen with extensive help from Anjum Mukadam. This manual was written by Russell Owen.