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-x.x.x.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.openmotif.org/ 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. Once installed properly, Imakefile should find the libraries and create a suitable makefile for your system during the compilation of of XmCCD described below. 3. SBIG Linux library routines. There will be a version of these in the xmccd package in its sbig subdirectory. If you want to check the original, go to the SBIG Linux website, currently at http://www.sbig.com/sbwhtmls/devsw.htm#Section%20IV 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-x.x.x/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 that the ones that are included here. 4. fxload I have included the most recent version of this USB utility in the xmccd distribution 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. 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 also get 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. 6. cfitsio These are the fits libraries and utililites. More to come ... 7. imageproc This set of simple image processing programs enables dark subtraction and flat fielding. Alternative programs are available in the cfitsio package. More to come ... 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-#.# Note that libsbigudrv.a is in the sbig subdirectory. Should you update the library, copy the new version to this directory. The library name should be same, beginning with "lib". By default a USB camera is assumed to be connected. Before compiling, if a different interface is needed, change the line in xmccd.c that sets "camera_device =" accordingly. For the parallel ports, the value for the port variable is set in xmccd.c (near line 279) static int camera_device = 4; /* camera device */ Device 1 is LPT1, 2 is LPT2, 3 is LPT3, 4 is USB, 5 is ETH. Note the following line that would be used to set the ethernet IP address if needed. This is a temporary arrangement to enable USB and ETH interfaces. In the next version of xmccd the interface will be user-selectable from the control panel or a startup file. Create a Makefile from Imakefile xmkmf Build xmccd make Move xmccd to a directory in your search path such as /usr/local/bin mv xmccd /usr/local/bin The SBIG runtime library must be available. Ideally, simply copy the libsbigudrv.a and libsbigudr.o files to /usr/local/lib/ as root user, and then issue the command "ldconfig" to make the library known to the system. Usually Linux systems will run this command when they are rebooted as well, but doing it now will insure that it is available. xmccd will use ds9 for image display if it is present. The complete distribution for SAOds9 is available from http://hea-www.harvard.edu/RD/ds9/ Install it from their distribution. If you build it from source, the result will include the XPA binaries as well. Should you download the binaries instead of building from source, also obtain binaries for XPA and install them. XPA provides the communication between ds9 and XmCCD. Copy the executables for ds9 and the xpa functions xpaaccess, xpaget, xpainfo, xpamb, xpans, xpaset to /usr/local/bin . When xmccd has a new image it uses xpaset to tell ds9 to read the image, and the other xpa functions may be used to enhance communication between the display program and the camera control program. 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 sbig subdirectory of the xmccd distribution. I have included two implementations in the scripts subdirectory 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 cd to the fxload subdirectory and 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. 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 so run xmccd and control your camera. V. Run xmccd ------------ As a normal user start the program with the command line xmccd The program will accept the standard Motif options to change geometry and title. It is not yet sensitive to an app-defaults file. It will spawn ds9, and make a connection to the camera if it is available. 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. The files created by default will have root ownership, but if you have them present already with user ownership, they will retain it. This is generally convenient, so 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 file ``Save Frame As ... '' menu to whatever name you prefer. Each subsequent exposure will overwrite previous image.fits and track.fits files. In some systems the library routines may disrupt the system clock when images are loaded down from the camera. I have noticed that the parallel interface cameras in older, slower, computers may cause the system clock to lose several seconds each time an image is loaded. The problem does not appear to be very significant in USB cameras on the current generation of PC's. However, if you have not done this already, install and run an ntp daemon to synchronize your computer with network time standards. This version of XmCCD has been tested with ST-7, and ST-8 parallel interface cameras, the ST-9XE USB camera, the ethernet adapter, the AO accessory, a CFW-8 filter wheel, and Celestron GPS 11-inch and Meade 16-inch LX200 telescopes for the guiding interface. Other USB ST and STL cameras should work once they are supported in the Linux version of the udrv library from SBIG. The AO accessory is not yet implemented in this version, but software to use it is coming soon. 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, and implement a selection for feedback to the telescope drive system or to the SBIG AO-7 adaptive optical device. 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) October 19, 2004