Supported Cameras ================= Oxford Andor Apogee =================== Apogee was purchased by Andor which discontinued most of their product line except the Apogee Alta in 2018. In 2020 Andor was purchased by Oxford Instruments and with the closure of the Kodak CCD manufacturing facility in Rochester, NY, the last Apogee camera was discontinued as well. The library here will support Alta and Aspen cameras that were manufactured before 2018. It is dependent on the open source code developed by Dave Mills, The Random Factory, http://www.randomfactory.com . Please see the directory libapogeedrv for notes on the changes needed to the source distribution in order to use it with XmCCD. The SDK for other Andor cameras is not open source and we will not be able to provide support, even for the cameras we have. The included Andor Apogee library has been tested with the Alta U, Alta F, and Aspen cameras using external (IFW) filter wheels. Check the documentation in libapogee for more information on building a version for other models. Note that while Apogee cameras are well-designed hardware with high quality components, two failure modes have become apparent as the cameras age: loss of CCD chamber seal with moisture condensing on the cold sensor, and shutter inoperability. Both modes of failure may not be reparable due to limited availablity of parts or expeditious repair services. The CCDs may be transplanted into new hardware by companies such as Diffraction Limited and Fingerlakes Instruments. Installation Instructions for XmCCD with the Apogee 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 your suggestion here. I. Required 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. XmCCD has been tested most recently with Opensuse Leap 15 and shared libraries are included that have been complied on Linux. Code is also included to re-compile the libaries for other distributions if needed. Download the DVD version of Opensuse Leap 15 or equivalent for the distribution of your choice. Install the default system, but include "development" versions of gcc. We typically include almost everything! After installation is complete add packages for -- Motif development (for the user interface) -- fxload (required to load firmware to the camera) and you should be ready to install and run the software. 1. XmCCD --------- Our website http://www.astro.louisville.edu/software provides: xmccd-#.#.tar.gz As root or superuser, copy this to /usr/local/src. Untar the archive with the command tar xvzf xmccd-#.#.tar.gz where "#.#" here will be a version number. 2. Motif libraries ------------------- XmCCD uses a Motif user interface. Your system will need a "development" package for Motif (or LessTif) to provide libraries and header files needed to compile xmccd. In Opensuse the easiest way is to use the system software management program to search Suse archives for Motif and install from their package. Other distributions should have similar services, or may already have Motif installed. If you are unsure whether your system has Motif, look for library files such as libXm.a, libXm.la, and libXm.so in /usr/lib for Suse 12.2, or perhaps /usr/X11R6/lib for other distributions. The makefiles for xmccd and xmccd1 require links to these libraries, and expect them in /usr/lib. You may need to edit the makefiles for distributions other than Opensuse if the libraries are not in /usr/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 Motif, or make changes described below. 3. FITS libraries ----------------- Astronomical images are stored as Flexible Image Transport (FITS) files and we use the cfitsio libraries in building xmccd. We recommend installing the libraries system-wide as root user. Note that if your system already has libcfitsio installed this step is not necessary. cd libcfitsio ./install_cfitsio 4. FITS utilities ----------------- A set of fits utilites is available in our ALSVID package. See our website for details. 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. A copy of the most recent binary at the time this version of XmCCD was built is included in ds9-#.# (where #.#is the version number). cd ds9-linux-#.# ./install_ds9_64bit It is simple to install the binary for ds9 by downloading it from the developer's website if you want the most recent version, or a version for another operating system http://hea-www.harvard.edu/RD/ds9/ and copy it to /usr/local/bin/ It may also be compiled from source although the complexities of the software make compiling likely to fail on "cutting edge" versions of Linux. We recommend using the binary. SAO_ds9 stores your preferences in a .ds9 file in the your home directory. You may want to read the manual to understand all the features, but one of them is that it communicates with other software through an "XPA" protocol. We use this to inform ds9 each time there is a new image, and to obtain region coordinates so that subframes can be read quickly if desired. XPA is built into xmccd1 and ccd, and it may also be used externally if you have scripts that are interacting with the images and the telescope control system. 6. XPA ------ SAO_ds9 uses the XPA communication library and utilities. A recent version of the source is included in XmCCD and must be compiled and installed: cd xpa-#.# make clean ./configure make make install ldconfig The ldconfig command will assure that the new fits and xpa libraries are recognized by the system. The XPA website has more information and updates: http://hea-www.harvard.edu/RD/xpa/index.html 7. Apogee Library ----------------- There is a version of the driver library in the libapogee subdirectory of the XmCCD package. The libapogee directory in the XmCCD distribution also includes a script for installing the library and include files. cd libapogee ./install_apogee_usb The library has been compiled from the source code included in the libapogee/src directory. These are Open Source programs from Dave Mills, The Random Factory. There are some small additions and modifications necessary to link the driver code, which is written in C++ and tcl, to the C programs used for XmCCD. If you need to rebuild the library or extend the source, see libapogee/README for documentation. It should not be necessary to recompile the library if you are using Suse 42.3, or another recent distribution. Opensuse no longer supports 32-bit operating systems. The install_apogee_usb script copies a rules file to /etc/udev/rules.d/ that should set read and write permission for the camera device and allow you to run the camera with normal user priviledges. II. Compile and install the XPA interface ------------------------------------------ cd xpaccd setup_apogee make clean make make install If you also have other cameras, you should rename xmccd1 and xpaccd to be unique, for example, xmccd1_sbig and xmccd1_apogee. The xmccd program talks only to xpaccd and is not specific to the choice of camera. III. Compile and install the user interfaces -------------------------------------------- cd xmccd make make install cd xmccd1 ./setup_apogee make make install The protocol files used for xmccd1 are the same as the ones used for xpaccd. Do not edit the protocol.h file here once you have edited it for xpaccd. The binary xmccd does not depend on the camera type, but xmccd1 does. If you also have an Apogee camera, or use different camera and filter combinations, create unique executables for each one and rename them. IV. Test that the USB system recognizes the camera and uploads firmware ----------------------------------------------------------------------- With the camera power off, plug the camera's usb cable into a usb port on your computer. Apply power and after a brief delay the camera lights should respond. For a diagnostic you could try lsusb and look for an identifcation for your camera. Apogee cameras do not load firmware (unlike SBIG cameras). The only issue you may have with the USB bus is the permission assigned to the device, since it should offer rw access to a normal user. The rules file that is installed will do this on recent Linux systems. If it does not work, a temporary fix as root would be chmod a+rw /dev/bus/usb/###/### where ### are the bus id's you see in lsusb. Older distributions of Linux also may not have an up-to-date usb id file. A copy of a recent one is in docs/usb . The README in that directory describes how to install this file. With a recent usb.ids file, the lsusb list will show "Apogee" in the device attributes. V. Install a configuration file for the user software ------------------------------------------------------ Copy a configuration file in xmccd-#.#/prefs/ to /usr/local/observatory/prefs/prefs.ccd and edit it to suit your camera. The prefs file is used to name the filters in your camera filterwheel and record tracking defaults for autoguiding on your telescope. If the file is not found, the compiled-in defaults will be used. Also create a subdirectory /usr/local/observatory/status As root user -- cd /usr/local mkdir observatory mkdir observatory/prefs mkdir observatory/status chown -R observer.users observatory where the last command would give ownership to the user who is running the camera. Alternatively (although less secure) allow any user to read and write to the tree. The programs xmccd1 and ccd read prefs files and write status files in this tree, as do the companion programs xmtel1 and tel. Some of our specialized scripts which are offered as examples here also use files under "observatory" to control flow. VI. Start the XPA server ------------------------- We recommend starting the xpaccd server in the directory where your image files will be stored. In routine use, where the camera is turned off except during the period of use, first be sure that xpaccd is not already running. One way to do this is killall xpaccd Once an Apogee camera is connected and initialized itself, start the server with the this sequence cd data xpaccd where "data" is the directory into which you will store your image files. On a given night, start with an empty directory to be sure you do not overwrite older images with new ones since the default naming sequence will begin again with a new start for xpaccd. This operation should be done as a user. It should not be necessary and is not desirable to do this as root. When the server starts the ccd driver, the driver will read a configuration file that is by default in /usr/local/observatory/prefs . Images acquired will be saved in the directory in which the server is started. The xpa server is compatible with XmTel, our telescope control software, but telescope and other controls are through their own servers, for example cd data xpatel In this case you may have "queue" files for data acquisition ready for xmtel in the data directory. Both xpaccd and xpatel will access scripts that are conveniently kept in /usr/local/bin, or in your own $HOME/bin directories. VII. Start the user interface ----------------------------- Once the server is running with the camera driver you may control the camera using the xmccd xpa user interface. The camera fan and the "on" light will indicate that it has loaded firmware. To use the xpa interface cd to a local directory where you will save images and issue the command xmccd The program will spawn ds9 for image display and open a window to control the camera. The user interface and the server do not have to be on the same computer. See the REMOTE file for instructions on how to set this up to work over the network. The protocol makes very low demands on network resources. Alternatively, xmccd works very well under a VNC server with TightVNC as a client for an "on-site" experience at remote observing. VIII. Run the camera from the command line ------------------------------------------- Use the command line with setINDI to run the camera without a user interface. IX. Alternative direct camera control interface without XPA ------------------------------------------------------------ The command xmccd1 will run the camera without an XPA server. You should not start xpaccd if you want to use xmccd1. The xmccd program requires that xpaccd is running. X. Filter wheels ---------------- Apogee cameras do not have an internal filter wheel. XmCCD allows you to use an external filter wheel and incorporate its control as an executable called by xmccd. Suport for the IFW-3 filter wheel is included here, and can be modified for others. Support for the Apogee filter wheel may be added in this development cycle but is is not currently in the software. XII. Scripts ----------- There are several scripts given in the the xmccd distribution as examples. Two of them -- transfer_image set_camera_filter should be edited installed in your computer's /usr/local/bin/. The first one is called by ccd to initiate an image transfer to ds9. The script provided does this by running setxpa locally. If your instance of ds9 is on another computer, you may need to use this to copy files or handle other tasks following the acquisition of an image. The second one is used to run an external filter wheel. A dummy version should probably be installed even if you are using an internal filter wheel to help the software start up smoothly before it knows your system configuration. There is also a program "ccd_monitor.sh" which may be started as a daemon and allowed to run during the entire data acquisition if you want to process images with a script after they are stored. It looks for a short timestamp file ccdnewimage in /usr/local/observatory/status as a flag that there is new data to work on. The file ccdnewimage is written by another script ccd_process.sh that runs (when the option is selected) every time the camera stores an image. The purpose of the two scripts is to separate the work done post-processing from the actual exposures and to avoide threading conflicts in Python. One very useful result is that the ccd_process.py script that is called by ccd_monitor.sh can make guiding corrections based on stars selected in ds9. Instructions on how to do this will be in the documentation on the XmCCD wiki. With this feature, if the telescope can take images without guiding that are of high quality in a cadence, for example, of 100 seconds, you can effectively run on a single target unattended for hours with feedback from the images you acquire to keep the telescope on target. We use this for real-time photometry with AstroImageJ. XIII. Send your comments ---------------------- Please let me know how this is working for you and what features you would like to see added. There is a short TODO list in the main directory. John Kielkopf (kielkopf@louisville.edu) 21 September 2019