The program "ccdtool" is a windowing application for acquiring images and managing the San Diego State CCD controller. It is written in ANSI "C" for the Solaris 2.x operating system. It is written using Xview, which is a library conforming to OpenLook graphical user interface standards. Users will need Xview libraries as well as X11R5 libraries to compile. The current revision level is 1.5.2.
To download a compressed postscript version of this document click here,(if you have problems, hold down the shift key and then right click on the link) CCDtool_new.ps.gz
The program is invoked by entering "ccdtool" in an X window. The window shown below will appear, with the "Welcome to CCDTool" message indicating that proper communication has been established with the SBUS interface board. The header gives the program name, revision level, and date of current revision. The five buttons on the menubar create additional windows when pressed, or call up a sub-menu displaying additional options. Pressing the Quit button to the right will bring up the Quit window verifying that the user wishes to terminate program execution. This is the correct way to quit CCDTool.
During program start-up, CCDTool reads a file named /usr/local/etc/ccdtool/ccdtoolconfig."machine name" for initial configuration parameters. For the development system at SDSU the machine name is "suicide", so the file name is ccdtoolconfig.suicide. An alternative is to keep a copy of the setup file in the user's home directory, and name it ".ccdtoolrc". If such a file exists it will be used for the setup parameters rather than /usr/local/etc/ccdtool /ccdtoolsetup."machine name" for the default setup parameters. This can be useful for users who wish to save defaults that differ considerably from the default that is maintained for the general user.
The text area below the buttons is a scrolling display window that reports program operation to the user. In this example the contents of a sucessful setup sequence are displayed. The scrollbar to the right allows unseen text to be examined, and the screen can be expanded by dragging the corners. New text is appended at the end of previous text, but will only scroll if the last line of text is currently visible in the window.
In the default configuration, the window reports completion of requested operations or error conditions. A more comprehensive operating log can be enabled by pressing the Setup button with the right mouse button (bringing up the window shown below), and then selecting the "Properties..." window (shown on the left), and enabling the "Show Commands" option. This will print all commands sent to the controller boards, as well as their replies to the SUN. It can be useful for troubleshooting, though it significantly slows program execution because of the time needed to update the display window.
To bring up the Setup Window, right click "Setup" in the main CCDTool window and then select "Configure CCD". This will display the window shown here. The CCD Setup window is used to set all operating parameters relating to the CCD and its readout, and to load appropriate software to the two DSPs in the controller. The "File" button at the top of the CCD Setup window brings up a sub-menu giving additional options including "Load CCD Setup" which loads the setup parameters from a disk file with the "Load CCD Setup..." option. The current contents of the window can be saved in a disk file with the "Save Current CCD Setup As..." button. Default values of the Setup should be saved in the /usr/local/etc/ccdtool/ccdtoolconfig* file once a standard operating mode has been developed. The default parameters will be loaded into the Setup window but the user must still Apply them by hitting that button.
A check mark to the left of each line will cause that item to be executed when the "Apply" button of the window is pressed. Items are executed in order from the top to the bottom of the window. Clicking on "Select All" will check all the items so they will all be executed when "Apply" is clicked, and "Clear All" will uncheck all the items. Clicking "Reset" will set the contents of the window back to the values last read in from disk, either the default values when the program started up or the values last read in with the "Load CCD Setup..." button.
The two DSPs located in the controller must have application software loaded into them to operate the CCD. Software can be downloaded from the SUN by writing the contents of a compiled and linked DSP load file written by the Motorola linker. The download procedure executes by repeatedly calling the WRM (Write to Memory) command that is implemented as a boot command which is loaded into each DSP during power-up or after being reset. The load file is specified on the "File:" line. Alternatively, the application software can be loaded into the DSP from on-board EEPROM with the Load Application (LDA) command, which requires an application number from 0 to 9.
Several scripts have been written to generate the application software load files. The boot, or system, program is linked with each application program and put into the load file even though it is not downloaded so that the application program has correct addresses to jump to. It is vital that the boot program be used for generating the download files be exactly the same as the boot program resident in the boot EEPROM on the board so addressing conflicts are eliminated. There are currently no safeguards against this and the symptoms of it having been done are minimal - the system just dies.
A description of each item in the Setup window follows -
When the Setup procedure is executing the four buttons at the bottom will be replaced by a single button labeled "Abort Setup". The current Setup operations will be suspended and the four buttons will reappear at the base of the window if Setup is aborted. Currently there is no automated time-out so the user needs to watch for the setup operation taking longer than expected. With the CCDTool display area set for error reporting only (by not selecting Show Commands in Properties window), the setup takes a few seconds to execute in its entirety, including the download of two large application files. With command reporting on it takes much longer - maybe a minute or so.
The program scans the list of parameters and filenames before executing any of the items to check if the filenames exist and if the parameters are in range. If any of them aren't correct, an error message is generated inviting a correct entry, after which the user must re-Apply. For an exposure to be taken, the Timing board, Utility Board, Power On, and Dimensions buttons must all be checked during the apply, othewise a warning message "Incomplete Setup" will be displayed in the text are of the main CCDTool window. The message "Setup complete" will be displayed upon sucessful setup of chosen options, or "Setup Failed" will be displayed if an error is encountered while applying the setup. Only a "Setup Complete" reply will allow the Expose button and the Action Buttons (see below) to be activated for use. If the setup cannot be sucessfully implemented, then most other commands will fail as well.
Once the controller and CCDTool program parameters have been set, exposures may be taken. To bring up the Exposure window, press the "Expose" button on the main window. Shown below, the Exposure Control window is divided into three areas - exposure control, action, and file control functions. The exposure control has the expose button which begins an exposure sequence that consists of executing the items that are checked in the Exposure Control area. The checked items are executed in order from left to right, top to bottom. Dark frames can be obtained by simply unclicking the "Open Shutter" item. The time to write to disk can be eliminated by unclicking the "Save to Disk" item. By checking the "Display" button, the image saved in memory will be displayed in an image display server such as SAOImage or Ximtool. The exposure time is entered as an integer or floating point number, and is effective to a resolution of one millisecond and up to times of 2**24 milliseconds, or 4.66 hours. For exposures greater than five seconds, a crude exposure timer appears in the footer of the window. During exposures the "Expose" button turns into an "Abort Exposure" button that will abort the exposure when pressed. Also visible during an exposure are the "Pause Exposure" button and the "Change Exposure Length" button. The "Pause Exposure" button temporarily suspends the exposure when pressed, brings up a window with the resume button, and resumes the exposure from the point where it was left off when "resume" is pressed. The "Change Exposure Length" button allows dynamic control over the countdown time remaining during the exposure sequence. To change the exposure time, edit the Exposure Time value and press the "Change Exposure Length" button to apply it. The time already elapsed from the original exposure time will be applied to the new exposure time, so if the elapsed time is greater than the new exposure length, CCDTool will immediatly begin to read out the CCD. Otherwise, the recalculated time left will be shown in the countdown timer in the footer of the Exposure window. Finally, by popular demand, the "# of Exposures" text area allows the user to take multiple exposures (such as calibration frames or multiple short exposures instead of single extended length exposures) without hitting the Expose button repeatedly. Hitting "Abort Exposure" at any time will cancel all the exposures waiting to be taken. It is left to the user to keep track of how many exposures have already been taken (by using the file incrementor, for example).
The buttons in the "Actions" area send commands to cause a specific action to be performed, quite apart from the automated exposure sequence. "Flush CCD", "Open Shutter", and "Close Shutter" do just what their names imply, and "Readout CCD" button tells the device driver to dump (write) the image to system memory. When the "Save to Disk" button is pressed the image that has already been read out and is now resident in system memory will be saved to disk according to the filename specified in the "File Control" area. Pressing the manual command buttons in order from top to bottom, starting with "Flush CCD" and ending at "Save to Disk", emulates the simplest possible exposure sequence evoked by pressing the "Expose" button. On the last of the manual buttons, the "Shift N Lines" button, the number of lines to be shifted is entered as a parameter under the button, and will cause N lines to be shifted on the CCD.
The "File Control" area assigns a file name to the disk file containing the image. The images are written in FITS format with a full set of header values presently implemented. The program starts out with the directory being the one in which CCDTool was started and with the filename which is specified in the /usr/local/etc/ccdtool/ccdtoolconfig.* file. If the filename is entered with a few numerical characters at the end then the "Auto-Increment" feature will increment the filename with each exposure, and display the new one each time. To utilize IRAF operations (see Appendix A) on raw pixel values, the image must be saved with a .fits extension. Any filename extensions will not interfere with the "Auto-Increment" feature of ccdtool as long as the last character before the dot-extension is a number (including leading zeros). The example above would increment to Cygnux_X1_006.fits.
Pressing the 'Rd CCD Temp' will send a command to the utility board to read one of its analog inputs (at the location Y:$C) that is normally connected to a temperature measurement diode located near the CCD. Software is executed to convert this number to degrees Celsius by first converting from digital counts to a voltage based on a calibration of the utility board, and then from voltage to degrees Centigrade based on the calibration of the diode. A default set of coefficients is hard-coded into ccdtool that assumes a CY7 Series silicon temperature diode supplied by Omega Engineering, where the coefficients are the same for all diodes of the series. If this diode is used the accuracy of the temperature measurement is about 2 degrees.
The FITS header editor allows the user to change the values of the FITS keywords. It is not possible to remove some of the keywords from the FITS Header Editor. The FITS Header Editor is opened by clicking on the "FITS..." button in the main window. The FITS Header Editor has three action buttons: File, Apply, and Reset. The File button allows the current values in the Editor to be loaded from or saved to a file. WARNING: It is not possible to modify an existing FITS header using this editor -- the image data will be LOST. The Apply button sets the FITS keyword values to those values in the Editor. The Reset button recalls the latest values that are stored in CCDTool. NOTE: If you click on Apply, then those are the values stored in CCDTool.
There are are four "sub windows" in the FITS Header window: Reserved FITS keywords, Important FITS Keywords, More FITS Keywords, and User Defined FITS Keywords. All fields except those in the Reserved FITS Keywords sub-window can be changed by the user. The FITS keywords in the Reserved FITS Keywords area are changed within CCDTool. Changes in these keywords are generally not reflected in the FITS Header Editor until after an exposure is taken. The other keywords need to be manually entered and applied in order to be correctly included in the FITS header along with the image. The Observation Date and UT are determined from the computer system.
The Editor is not case sensitive in the User Defined Keywords area. It will automatically convert the keywords to all capitals.
Individual commands can be sent to either of the two DSP-containing boards from the DSP window. TheDSP window is invoked with the button on the CCDTool window. The window consists of an input area which includes buttons and value input spaces, and an output area in the footer of the window. The "Board" buttons specify to where the command will be sent. The specific commands available depend on the board selected and will appear in the row of buttons following the "Boot Commands".
Five commands are common to all three boards and are resident in the boot program:LDA - Load Application - to load a numbered application program from on-board EEPROM to DSPRDM - Read Memory - Read DSP or EEPROM memoryRST - Reset - Reset the DSP and load its boot program from EEPROMTDL - Test Data Link - write back the argument as a system testWRM - Write to Memory - Write to DSP or EEPROM memory
Depending on the command button selected, the "Memory Space:", "Address:" or "Data:" label will enable if an entry in needed for proper command execution. A number (in hex) should be entered, and the Send Command button pressed to execute the command. All commands give replies to the program, which are displayed at the bottom of the window in the footer. Some commands, such as RDM, give numerical values, while others give the 'DON' reply to indicate that the command executed successfully. Unsuccessful command execution is indicated by an 'ERR' reply. No reply is indicated by the "Command" button remaining discolored and the program freezing up, hit the Abort Command button to un-freeze the program. Following these are application commands that are specific to each board. Clicking on the board selection causes a different set of commands to appear below the boot command list. They execute by pressing Send Command, as well.
In the example shown here, the timing board is given the WRM command to write data 4ae (hex) into address 11 of memory space P. The return value, DON, sent by the timing board, can be seen in the footer of the window. Commonreturn codes are:
0x444f4eDON (Done)
0x455252ERR (Error)
The Manual button allows the interactive testing of new DSP Commands by the user. The board header and the command must be supplied by the user, and then CCDTool will attempt to execute the command normally. The last digit of the header will be interpreted as the number of words sent to the DSP (limit 5), and the arguement prompts will apper in the lower part of the window to allow input of the arguement values. The reply displayed in the footer of the window will depend on the command sent, and on the DSP code currently in use, but in all cases, if the command is not understood, the footer will display ERR.
Makefiles - CCDTool must be compiled using either an old-style C compiler or an ANSI C compiler. It has been tested using Sun compilers SC2.01 and higher. The compiler type is defined by the tag "CC " located in the file, Makefile.common. Uncomment the compiler that is present on your system. The tag RANLIB is used when creating the CCDTool libraries. In Solaris, ranlib does not exist, so this tag should be assigned to echo, instead. Also, it is necessary to change some of the system libraries from SunOS to Solaris. These libraries are defined by the tag LD_OPTIONS. New versions of CCDTool have been modified to compile under Solaris using the SC3.0.1 C compiler. There is no guarantee that CCDTool will compile error-free on the first try on earlier versions of the C compiler, or on the gcc compiler.
In addition to compiling the actual C source code, it is possible to modify the templates used by devguide. The devguide templates are included during the make in the TARGET tags. If you do not want to generate the source code from devguide, you should remove the devguide tag from the TARGET list by deleting "ccd_devguide" from the tag "CCD_TARGETS" in the main Makefile. However, you should only do this after generating the code for the first time.
To compile CCDTool, type solaris.make or sunos.make (depending upon your OS), and the scripts will automate some the initializations and operations for you (such as defining the locations of compiler and of devguide and setting OS dependent values). Unlike a makefile, sunos.make and solaris.make must be executable.
Device Driver - A device driver is a way for user programs to read/write from/to a physical I/O device. The astro.c device driver is installed into the SUN system and is used to transfer data between the SBus Interface board and user programs. Using information stored on the SBus board, the device driver is installed/initialized first. User programs can then make system calls such as open(), read(), ioctl(), and close() to perform read/write operations between the user programs and the SBus board. The SBus board takes advantage of Direct Memory Access or DMA to transfer data indirectly from the SBus board to user memory. DMA registers residing on the SBus board are initialized/started to begin transfer of a block of data to the device driver. Once the block of data has been transferred to kernel memory first, the SBus board issues an interrupt request which is serviced by the device driver. The device driver sets up for the next block of data and transfers the previous block of data to user memory. This continues until all data is transferred from the SBus board to the user program. The device driver can also send small blocks of data from the user program to the SBus board. In this way, all the interface details of the communication between the SBus board and the user program are left to the device driver. The user program has only a few routine calls that are needed in order to read/write from/to the SBus board.
1. If any of the boards undergo a hardware reset for any reason CCDTool has no way of knowing about it, and will hang up.
2. The selection Show Commands in the Properties submenu of the Setup window gets reset to Show errors if the Setup window contents are re-applied.
1. If an error is received on a reply it is simply reported. The program should terminate its execution sequence and report it more compellingly to the user.
1. A facility to execute command sequences, or scripts, is planned. These would be stored on disk and executed a setable number of times.
The display capability for CCDTool relies on a display server being available to take the image data and show it on the screen. Common display servers are Ximtool and Saoimage, but any display server that works with IRAF (Image Reduction and Analysis Facility) will work with CCDTool.
When an image is sent to the display, it is stored in an image buffer there. If thisimage buffer does not correctly match the dimensions of the image size, then the image buffer contains mostly empty pixels, thereby wasting considerable memory and slowing down the speed of the display algorithms.
Every time an image utilizes less than 70% of the available image buffer, a warning message will be printed in the window from which CCDTool was started. The warning will be accompanied by a notice that the system administrator can fix the problem, and then gives the solution to the problem. For example the message:
IMPORTANT STATISTICS: buffer size: 65536 image size: 40000 only using 61% of frame buffer NOTICE: To improve display speed, ask System Admin to add this line to /usr/local/lib/imtoolrc: 41 1 200 200indicates that the file /usr/local/lib/imtoolrc is to have the information shown appended to it. That file should contain any custom image sizes that will be taken by ccdtool. The first number displayed in the error message corresponds to the next available empty slot in the frame buffer table, followed by how many frames are allocated (which is arbitrary, but the max is 4), and finally the width and height of the image to be placed in that image buffer. This file should be customized upon installation of CCDTool and should be made to contain the image buffers for all image sizes available on a particular telescope. The error message will be printed each time an inefficient image is displayed, so to have any changes that have been make to the imtoolrc file take effect, CCDTool must be exited and restarted in order to have any changes in the imtoolrc file take effect.
When ccdtool makes the initialconnection to the display server, it reads the usr/local/lib/imtoolrc file and creates a look-up-table (LUT) in memory. CCDTool then scans the LUT each time an exposure is displayed and uses the table to create a display buffer in which to house the image, which it sends to the display server. CCDTool chooses the frame buffer that contains the smallest residual empty buffer space. This buffer will be selected for displaying the image.
The image that is saved in memory is passed to the display server via thepipes /dev/imt1i for input and /dev/imt1o for the output. It is important that the display server be hooked up to these pipes, otherwise ccdtool will be unable to send the image. The first time the display option is selected, ccdtool attempts to connect to the display server. If the display server is not reached during a display sequence, then one of the following messages will be displayed in the ccdtool main window:
1) Display in progress opening connection *** Open Connection to Display Server failed Exposure OK, but no Display Possible
This error indicates that there is no display server detectable by CCDTool. This error will only occur during the first display sequence when CCDTool tries to connect to the display server. To alleviate the problem, open a display server and then continue to display images normally. The connection will be noticed by CCDTool and the images will be piped to the display in the future.
or 2)
Display in progress
***WARNING: broken pipe
Exposure OK, but no Display Possible
This error indicates that the display server was disconnected from ccdtool at some point after making an initial connection (i.e.. after displaying images). To rectify the situation, open a display server, and continue exposing normally. CCDTool will notice the connection and will automatically pipe the images to the server.
In no way does the display option affect the image that is saved to disk. The image resident in memory is safely saved to disk (assuming this option is checked in the Expose window) before the display sequence is initiated, so the display image is independent of the disk image, and any problems or errors during display cannot effect the image data on disk.
One word of warning: CCDTool's display sequence sends an image which has been scaled to 8 bits so the display server can receive the information. Although the values in the display server appear to be 16 bit numbers, they are NOT. The display servers estimate the original pixel value (very precisely, but as binned ranges), so the raw values are lost. This is NOT a bug in CCDTool, but in the way the display servers accept data. It is only apparent when performing IRAF operations on the image in the display buffer which has been sent by CCDTool.
IMEXAM and otherIRAF functions will work on the displayed image to a limited degree. Since most current Unix displays can only depict 256 colors, CCDTool sends the image to the display server after compressing the pixel levels to 8 bit values for viewing. Therefore, any analysis through IRAF of the image that was piped in from CCDTool will use only these 8 bit values. To perform the IMEXAM operations with usual IRAF V2.11 functionality, the image must have been saved as a ".fits " file in the filename space of the Expose window. This allows IRAF V2.11 to open the image without the RFITS conversion step being necessary. Then all image manipulation may be performed normally. For example, edit the filename in the Expose window to be filename.fits, and then expose as usual. Then simply type "imexam filename.fits" at the "cl>" prompt in the iraf window, and IRAF will load the file, display it, and wait for IMEXAM commands to be entered by the user.
MLOcam is the newest version of CCDTool customized for use at the Mount Laguna Observator (MLO). It utilizes the knowledge contained in the control micro, which interfaces with the telescope, for automatically updating the fits header with the appropriate RA, DEC, and other telescope supplied values. This should minimize the number of operator errors incurred during those "wee-hours" of an observing run where mistakes can sometimes go unnoticed.
The communication between MLOcam and the control micro is based on the functioning ofOMICS, the MLO Command Interpreter that allows a flexible user interface to send the fixed-format commands to the control micro. This frees the user from having to memorize cryptic commands, and minimizes the chances that unexpected responses from "nearly correct" commands will adversely affect the telescope's functions. It is important to note, however, that MLOcam needs the OMICS process to be running in advance to be able to receive the telescope data.
Tostart MLOcam, make sure OMICS is running, and then type mlocam into any xterm that is available (currently, MLOcam is the default CCD controller, so typing ccdtool will also execute MLOcam at Mount Laguna). The command line parameters that MLOcam currently understands are "-d" and "-n". They may be used individually, or combined (-dn, or -nd) in any order to have them implemented. The "-d" (debug) option sets MLOcam into runtime debug mode which displays the information being received from OMICS as it is converted for use in MLOcam. The "-n" (no-OMICS) option allows MLOcam to run independently from OMICS, but retains all CCDTool functions; the "no-omics" option, however, defeats the purpose of using MLOcam instead of CCDTool in the first place, and was only implemented for use in environments where OMICS was not available (at design time, for example).
MLOcam will, at startup, attempt to make aconnection with the shared memory segment of OMICS. This connection will be attempted a few times with error messages being reported as they occur. If no connection is detected, then a warning message will be displayed, and MLOcam will reset and try the connection sequence again. If a connection still isn't established, then MLOcam will abort the communications transactions and run in "no-omics" mode, behaving just like CCDTool. In this case, it is important that the user carefully update the Fits header by hand for each image that is taken. If the connection has not been successfully negotiated, then MLOcam should be quit and OMICS should be examined to insure that all the processes are running. To insure OMICS starts correctly, kill all the currently running OMICS processes. This is accomplished by performing kill -9 on the processes spawned by startup and startint (which are launch scripts for xtst, sw, voodd, tel, and int). Then, typing startomics in an xterm and OMICS will restart and be ready to connect to CCDTool.
After the connection has been successfully initiated, the Fits Header Editor will automatically display the information gleaned from OMICS during the last refresh of the Fits Header Editor. The new values for the Fits parameters will be refreshed when either the exposure sequence is started, or when the reset button in the Fits window is pressed. These values mirror those displayed in the OMICS display console window. The values in the header of the image are those that were accurate at the beginning of the exposure when the header is saved, not the values at the end of the exposure.
The six values that are automatically inserted into the header are the RA, DEC, Airmass, LST, UT, and the current Epoch. It is important to note that OMICS precesses the object's coordinates to the current epoch and passes these coordinates to the telescope for positioning. Therefore, the epoch in the fits header is the current epoch, and the coordinates are the actual coordinates of the object precessed to current epoch.
To compile MLOcam, only minor changes need to be made to distinguish it from CCDTool and the procedures outlined in the main text. In the OS-preparation files (sunos.make or solaris.make), editing the last line to replace "ccdtool" with "mlocam" at each occurrence on that "make" line will do the trick. Then, in Makefile , comment out the tag CCD_TARGETS and uncomment MLO_TARGETS. That was it! However, if CCDTool has already been compiled, then a make clean must be performed in the top ccdtool directory (it is only necessary in the tool directory, but do a full make clean just to be sure). Conversely, if MLOcam has been compiled, a make clean is required prior to compiling CCDTool.
Back to Document List page.