readcal

Command:	readcal
Contexts:	Network socket, serial console, stage2 only
Function:	Calibrate signal chain to bring in range of the ADCs.
Required Parameters:	None.
Optional Parameters:	If adulevel omitted, readcal just measures pedestal.
adulevel=	A number of counts, like 5000
channel=	[r] Select between red green and blue ADC channel
cellrow=	(Use otacal command instead of readcal, for OTAs)
dev=	[current] Select dev 0 or 1 (>= r5696 stage2 ONLY)

Usage

dev 0
readcal 5000
dev 1
readcal 5000

For most STARGRASP camera systems, the higher camera-level "cal" script is used to call readcal, and even then, it is typically not necessary to use readcal every time a system is powered on unless a boardset has been moved around or clock timings have been adjusted. Temperature changes and some detector-specific effects may also require readcal to be redone, but typically the values determined once are usable until hardware is changed. All of the readcal values are stored in the FITS header by tools like grasp_save_ota and restored automatically by tools like grasp_pon_ota meaning if this save/pon model is being used to restore state, it is advisable to create a new set of so called PONFITS reference files with which to power on your camera any time when clocking, voltages, operating temperatures, or boardset positions have been changed.

Alternatively, a camera-specific setup script could be used to restore the dacs which get set by readcal, which is preferable to re-running readcal each time the camera is powered on. The reason for this is that "readcal" is sensitive to many factors, and has the following prerequisites:

• clocking timings (clvset) must be set up first or the results are invalid.
• clocking voltages set by some kind of pon or any sequence of necessary dac commands
• geometry parameters (detsize) must be set or else readcal may fail trying to calibrate non-connected channels
• detector must be cold, or it could get so swamped with charge that reset levels are not reached
• detector must be cleaned properly first, and without major light leaks (to avoid same problem as previous item.)

A bad readcal operating point could result in an entire night or run of bad/noisy/dynamic-range-limited data. A warm or supersaturated detector, overwhelming the reset so it cannot get back down to a proper pedestal level, is the most common cause of readcal failure. Even if the readcal command does not fail, the result should be checked on a full image readout, as explained below.

Each pixel in the image has a pedestal, which should be around 5000 ADU once "readcal 5000" has been run, but there are always low level effects in the pedestal (tilt, negative or positive image leaking in) and so the best way to determine if the operating point resulting from readcal is good would be to readout and save an image with 32 bpp mode, which saves a cube where the first layer is the image, and the second is the pedestal, intended to be subtracted off. No pixels anywhere in this pedestal image should be at or near zero. Any FITS image viewer can be used to verify this.

What Does "readcal" Do?

Each pixel value generated by the STARGRASP controller is the result of multiple individual digital samples of the channel's internal Analog to Digital Converter (ADC) 0 to 4V range, shown above. The process used is known as Digital Correlated Double Sampling (DCDS). Although a variety of multi-sampling readout parameters are configurable at runtime with the cestlavie program and the clvset command, most STARGRASP CCD readouts sample the reference pedestal level (ped) for each pixel four times, and the video signal level (sig) four times. All eight of these samples must be within the 0-4V limits of the 16-bit ADC (0..65535). The difference between the average (arithmetic mean) of the four reference pedestal values is subtracted from the average of the video to produce the pixel value found in the FITS file (unless saving in "3d" or bpp=32 mode for diagnostics.)

All four of the reference pedestal samples must always be above the floor that the A/D can measure, and an internal offset voltage (per channel) must be used to "steer" the value to something above zero, but not too high. The side effect of being too high would be reduced dynamic range. Steering the pedestal in to around 5000 ADU already means that the highest measurable value is around 65535 - 5000 or 60535. Going higher would further reduce the maximum signal that can be measured (assuming detector full well is not reached first.)

In order to converge more quickly, the starting point for the readcal algorithm is the last known calibration value. If it fails to converge, that offset voltage (and next starting point) is set to 0 Volts. For this reason, sometimes readcal must be run twice to succeed, especially if incorrect values (from a different boardset or preamp, for example) were used as the starting point.

If readcal is taking a long time to complete, or of it is failing to converge, it is often because a new starting point should be recorded. The other common cause of failure can be super-saturation of the CCD. The CCD should always be dark (shutter closed, no major light leaks) and be cleaned multiple times before attempting readcal.

Restoring readcal Without grasp_pon

The preferred method of restoring the entire operating point of the detectors is to use a tool like grasp_pon_ota or other grasp_pon_<detectortype> C program, which reads a FITS file and communicates directly with the controllers to restore everything. The keywords which specifically control readcal levels are named DAC_CAL* and appear in a space-delimited list in a header keyword.

If this method is not being used (it is only fully implemented for OTA CCDs), then correct "readcal" levels can be extracted from a previous stargrasp log message history and converted into the right "dac 2 ..." commands, sent from a script. The appearance of the readcal parameters in the log will be similar to this:

> dev 1
> readcal 5000
+ ch 0 offset   -39mv mean= 5100.8, 7082.7, 1981.8 rms=33.1,35.4, 8.0
+ ch 1 offset   -19mv mean= 5013.2, 6885.6, 1872.4 rms=32.1,34.3, 7.2
+ ch 2 offset   -18mv mean= 5197.3, 7253.9, 2056.5 rms=35.1,37.8, 7.1
+ ch 3 offset    -5mv mean= 53....

with up to 8 channels per "dev". If the current dev was dev 0, channel 0 starts at dac 2 7 ... and counts backwards. For dev 1 as shown above, the 8 dac "dac 2 15" through "dac 2 8" adjust the offset. Note the reversal here, on both sets of dacs. For example, to restore the -39, -19, -18, and -5mV calibration shown above, send commands:

dac 2 15 -39
dac 2 14 -19
dac 2 13 -18
dac 2 12 -5

It is also possible to issue the following command after a "readcal" result that has been verified:

dac 2

which will print all of the values in dac 2, the first 16 of which need to be restored to get back to the same readcal operating point.

CAUTION! It is relatively harmless to adjust "dac 2 0" through "dac 2 15" but use extreme caution when manually sending dac commands since stray voltages on other channels could harm the detector. See the manual page for dac for more information.