Installation Instructions for XmCCD with the SBIG Library ========================================================= This is a recipe for installing XmCCD and auxiliary software especially for those who may not have experience with Linux system management. If you try this and find I have left out something, please let me know and I will include it in the next version. I. Resources ------------- First, you will need the software sources. It is best to compile xmccd from the source to be sure that it will work with your system. More complex programs such as the display software ds9 are available in binary form, though even in that case it is best to compile from the source if you do not find the task too daunting. You will need these programs or files before you can take the software for a test run: 1. xmccd-#.#.tar.gz This is the gzipped tarfile for the software. The latest version from http://www.astro.louisville.edu/moore/software will include the SBIG udrv library that was most recently tested with the program. 2. LessTif or Motif libraries. Your system may already have what you need. If you are in doubt, look for library files such as libXm.a, libXm.la, and libXm.so which are usually in /usr/X11R6/lib. You might also simply try to compile xmccd (see below) before you proceed to install Motif, and if there is an error message that a library is missing, that is a good indication that you need to install either LessTif or Motif. Also, if you succeeded in compiling XEphem from source, then you have the necessary library files already. If you find you do not have one of these on your system, the simplest approach is to go to your Linux distribution and retrieve a package. If you have a choice, take the one that is installed by default since it is most likely to be set up properly. Alternatively, use the opensource version of Motif from http://www.motifzone.net or the Gnu-licensed version of LessTif at http://www.lesstif.org/ select "Downloads" on the webpage, retrieve the last stable version, and follow their installation instructions. Recent sources that are known to work with XmCCD are also available directly from the XmCCD web site. Once installed properly, Imakefile should find the libraries and create a suitable makefile for your system during the compilation of XmCCD described below. 3. SBIG Linux library routines. There will be a version of these in the xmccd package in its sbig subdirectory. You should use the included version if at all possible because it will have been tested with this version of XmCCD. The sbig directory in the XmCCD distribution also will include kernel modules and scripts for installing them. If you want to check the original SBIG library source, go to the SBIG Linux website, currently at http://www.sbig.com/sbwhtmls/devsw.htm#Section%20IV At the time this distribution of xmccd was packaged, sbig kernel modules were available for the 2.4 series Linux kernels. Modules for 2.6 kernels were expected soon. Note that if you choose to download their development package, make sure that the libraries and headers have the same names as the ones in xmccd-#.#/sbig/. SBIG also supplies files that are uploaded to their USB cameras when they are detected on the bus. It is quite possible that there will be newer versions of these "firmware" files available from SBIG than the ones that are included here. See below about copying the sbig files to appropriate locations on your system. Also note that the header file sbigudrv.h must be present or linked from the xmccd source directory. This distribution includes that link, assuming the source for sbig files is in the xmccd-#.# tree. The version of the header file distributed by SBIG has the development environment set for Windows, but that has been fixed in the files distributed here. If you download a new version you should check the first few lines of the header file to be sure that it is set for your environment. 4. fxload You will need the USB fxload utility in order to run the SBIG USB cameras. I have included the source code for most recent version of this USB utility on the XmCCD web site because it was not part of the Slackware distribution that I use. There are instructions in the sbig subdirectory for obtaining fxload from its website if you prefer. You do not need fxload if you are only going to be using the parallel port ST7 and ST8 cameras. 5. fitsio The FITS file library known as "fitsio" is required. XmCCD uses it to write fits files, and fits utilities "imdark", "imflat", and "imrows" included in the distribution use the libary for reading and writing image files for dark subtraction, flat fielding, and extracting spectra. The source for the fitsio library is also on the XmCCD web site, as well as a link to the original. 6. ds9 This is the powerful image display software from the Harvard-Smithsonian Center for Astrophysics . XmCCD uses it to display the images and to provide image analysis and file handling. Go to http://hea-www.harvard.edu/RD/ds9/ and retrieve either the binary version for Linux, or the source code. You will also need the xpa binaries if you do not compile from source. Copy the executable for ds9 and the xpa utilities to /usr/local/bin/ . You may find it helpful to have a copy of the Reference Manual, because although the program is fairly easy to navigate from its menus, there are many features to learn about. The source code and the reference manual are on the XmCCD website. 7. Cinepaint or GIMP XmCCD produces images in the FITS (Flexible Image Transport System) file format. The images are 16-bit unsigned integers, at their best when processed for display with a 32-bit image processing program such as Cinepaint. GIMP, often included in Linux distributions, may work but it cannot handle the full dynamic range of images acquired with SBIG CCD cameras. II. Compiling and installing XmCCD and ds9 ------------------------------------------- Untar the file xmccd-#.#.tar.gz . By default it will create a directory xmccd-#.# with the command tar -xvzf xmccd-#.#.tar.gz Set your current working directory to xmccd-#.# cd xmccd-#.# It is best to locate the sbig files where they easily can be updated and maintained, independent of xmccd. The scripts for loading drivers assume that sbig is in /usr/local. The following command will copy the sbig directory cp -R sbig /usr/local/ The following commands will copy the library files to /usr/local/lib and make them available to the linker cp sbig/lib* /usr/local/lib ldconfig Usually Linux systems will run the ldconfig command when they are rebooted as well, but doing it now will insure that the new library is available. The source files for XmCCD are in the xmccd-#.#/xmccd directory cd xmccd Create a Makefile from Imakefile xmkmf Check that the filterwheel type following line 182 in the source code file xmccd.c matches the type on your system. In this version you must change the filterwheel designation in the source code. By default it is set for the CFW10 (not 8!). At the same time you may want to change the labels to match those for your filter sets. In the future we will provide for a startup file that will make it easier to change this at run time. Build xmccd make Copy the xmccd executable to a directory in your search path with cp xmccd /usr/local/bin Finally, the XmCCD distribution includes a few fits file handling utilities that are useful for preliminary image processing. These are in the fits subdirectory. From the xmccd-#.# directory cd fits make make install The binaries will be in xmccd-#.#/bin and may be copied to a public directory. Again form xmccd-#.# cd bin cp * /usr/local/bin will make available imarith, listhead, modhead from the fitsio example library, and imdark, imflat, and imrows for dark subtraction, flat fielding, and spectra extraction. XmCCD uses ds9 for image display, and the xpa utilities for communication. Compile and install ds9 and xpa as described earlier. III. Install the kernel modules ------------------------------- The appropriate kernel modules must be loaded before running xmccd. Scripts that do this have been provided by SBIG and are in the bin subdirectory of the xmccd distribution. I have included two implementations here with names insmod_sbig_lpt insmod_sbig_usb A simple way to use these is to copy them to /usr/local/bin and to execute them in a startup script for your system. For example, in Slackware the appropriate startup is rc.local, which should have the line /usr/local/bin/insmod_sbig_usb if you want to insert the usb modules when the system boots up. IV. Setting the USB system to recognize the camera and upload firmware ---------------------------------------------------------------------- The USB system in current linux distributions will recognize devices that are plugged in while the computer is running. There are some things you need to do, however, to let the system know about the SBIG cameras, and to provide the system with a utility and instructions on what to do when it finds your camera. Here's a step-by-step list extracted from the sbig/README.txt instructions. 1. Install fxload if it is not already installed Check if you have fxload already available. It should be in /sbin, so look for /sbin/fxload. If it is not there, then as root untar the fxload source package somewhere such as /usr/local/src, cd to the fxload subdirectory, type make and if all goes well, then make install The makefile is set to install fxload in /sbin, the man pages in /usr/share/man/man8, and a hex file in /usr/share/usb/ . It will create /usr/share/usb/ if it does not exist. This is good! You will need it later. 2. Update usb.usermap Look at the file sbig.usermap in the sbig subdirectory of xmccd-#.# It has a comment line and three instruction lines that must appear exactly in the system file usb.usermap . Look at this file using cat /etc/hotplug/usb.usermap If it only contains the header comment line, then you can simply cd to the sbig subdirectory of xmccd and cp sbig.usermap /etc/hotplug/usb.usermap If there are already entries in your usb.usermap file, then edit it to add the lines from sbig.usermap exactly as they are in SBIG's file. 3. Install the firmware files From the sbig subdirectory of xmccd, copy the firmware files to /usr/share/usb. You will need to create /usr/share/usb/ if it does not already exist, but installing fxload from source will have made this directory for you: mkdir /usr/share/usb/ cp *.hex /usr/share/usb/ 4. Install the script file sbig From the sbig subdirectory, copy the sbig script to /etc/hotplug/usb cp sbig /etc/hotplug/usb That should do it! Once the modules and usb routines are in place, when you plug in your camera, the system will recognize it and upload the firmware. Once that has happened you should be able to run xmccd and control your camera. You may need to reboot your system to get the usb utilities to work properly. Remember to make the module insertion automatic as noted above, or to do it as root user after the system has booted. Turn on the camera. It should upload the files it needs and be ready for use after a few seconds. All should be well when the fan is running. V. Run xmccd ------------ As a normal user start the program with the command line xmccd to connect to a usb camera. The program will spawn ds9, and make a connection to the camera if it is available. The USB interface is the default, and the command "xmccd -usb" will force this option but it is not required. Alternatively, if you have a parallel port camera, use a command such as xmccd -lpt1 Ports lpt1, lpt2, and lpt3 are available. Remember that you must first install the kernel modules appropriate for your USB or parallel port camera, connect the camera to the computer, and turn on the camera power. ds9 will attempt to display track.fits and image.fits, the default image and track ccd files. These files should be present in the working directory from which you start XmCCD. If not, they will be created when you take an exposure. It is advisable to set aside a directory from which you will run xmccd and in which the image files will be kept. Once an image is acquired and visible in ds9, you should save it with the ds9 command menu "File -> Save Frame As Fits" to whatever name you prefer. Each subsequent exposure will overwrite previous image.fits and track.fits files. XmCCD relies on the ds9 user interface to allow you to view and save images. This version of XmCCD has been tested with ST-7, and ST-8 parallel interface cameras, the ST-9XE USB camera, a CFW-8 filter wheel, and Celestron GPS 11-inch and Meade 16-inch LX200 telescopes for the guiding interface. As of this date, all SBIG USB cameras currently in production, and the ST7/8 parallel cameras should work. The AO accessory is not yet implemented in this version, but we have one and software to use it is coming soon. STL cameras should be available to us by August 2005 and more versatile filter wheel handling will be incorporated in XmCCD soon to accomodate the newer cameras, different filter sets, and the CFW10. XmCCD will attempt to take tracking exposures during a long image exposure. Since it takes a few seconds to download and display a tracking CCD image, this is useful only for imaging exposures greater than about 10 seconds. The tracking image will be updated in the ds9 display during the longer image exposure, and may be used with the control panel for manual guiding. Future versions of XmCCD will automate the guiding process, allow for subarea readout of the primary and tracking CCD's, and implement a selection for feedback to the telescope drive system or to the SBIG AO-7 adaptive optical device. Work on this is in progress at the time of this release. Have fun. Let us know if there are features we could add that would make this software more useful for you. John Kielkopf (kielkopf@louisville.edu) March 5, 2005