Supported Cameras
=================

The driver should automatically recognize any Apogee Alta series
camera with a USB interface.  

It has been tested with the U16M, U9000, and U6 models with external (IFW)
filter wheels.  Check the documentation in libapogee for more information.

We have not tried other Apogee cameras, and the driver is not configured to use
the parallel interface or the ethernet interface versions of their hardware at
this time. However, the source code for the library provides the resources for
these options, and the framework we use here could be modified to handle any
hardware that is in the open source library.


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 11.1.  Earlier versions or other distributions of
Linux may have issues with the software that handles the USB interface, although
these can be resolved and we are using it with OpenSuse 10.0 series
installations.

Download the DVD version of Suse 11.4 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)

and you should be ready to install and run the software for an Apogee camera.
  

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 11.1 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 11.1, 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 Suse 11.1 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 either LessTif or Motif, or 
make changes described below.



3. FITS libraries
-----------------

Astronomical mages 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

Should it be necessary to rebuild the library, 

cd libcfitsio/src
./configure
make

cp libcfitsio.a ../
cp fits*h ../
cp longnam.h ../

cd ../
./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_32bit

A 64-bit version is available there too, although at this time we recommend
running the cameras under a 32-bit OS.

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.



6. XPA
------

SAOds9 uses the XPA communication library and utilities.  A recent version is
included in XmCCD

cd xpa-#.#
./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 is 

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 64-bit 
Suse 11.4, or another distribution of the same vintage, with a USB camera 
model in production before July 2011. If you prefer the 32-bit version you will
have to recompile the library.  This is a simple task and instructions are in
libapogee.

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 INDI components
--------------------------------------------

Set your current working directory to the xmccd-#.# release directory. 

Compile the code in each of these directories as root user:

cd liblilxml
make

cd indiserver
make
make install

cd indiutil
make
make install

cd indiccd
./setup_apogee
make
make install

The last "make install" will place a copy of the indi driver "ccd" in
/usr/local/bin/.  If you also have an Apogee camera, you may rename the drivers
to be unique, for example, ccd_sbig and ccd_apogee.


III. Compile and install the user interfaces
--------------------------------------------

cd xmccd
make
make install

cd xmccd1
./setup_apogee
make
make install

The binary xmccd does not depend on the camera type, but xmccd1 does.  If you
also have an Apogee camera, rename the executables to unique names such as
xmccd1_sbig and xmccd1_apogee.


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.


VI.  Install a configuration file for the user software
-------------------------------------------------------

Copy the 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 the filter wheel and to set
tracking defaults for autoguiding on your telescope.  If the file is not found,
the compiled-in defaults will be used.  


V. Start the INDI server to use the INDI version
------------------------------------------------

Once the camera is connected and has uploaded its firmware, start the INDI
server with the command


cd image_directory
indiserver ccd


This operation should be done as a conventional 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 . Images acquired will be saved in the directory in
which the indiserver is started.  The server is compatible with XmTel, our
telescope control software.   To start them simultaneously,

cd image_directory
indiserver ccd tel


VI. Start the user interface
----------------------------

Once the server is running with the camera driver you may control the camera
using the xmccd INDI user interface.  The camera fan and the "on" light will
indicate that it has loaded firmware.  To use the INDI 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.


VII.  Run the camera from the command line
------------------------------------------

Use the command line with setINDI to run the camera without a user interface. 


VIII.  Run the camera from XEphem
---------------------------------

With the indiserver running as described above, start xephem as usual. Follow
the menus --

View -> Sky View
Telescope -> INDI panel
Connect
ccd

This opens a display with options to control all camera parameters.


IX.  Alternative direct camera control interface without INDI
-------------------------------------------------------------

The command

xmccd1

will run the camera without an indiserver.  You should not start the indiserver
with the ccd driver if you want to use xmccd1.  The indiserver requires xmccd.


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.

To use an external filter wheel, edit protocol.h and set 

#define FILTER_WHEEL  EXT_FILTER_WHEEL

Edit the set_camera_filter script to execute the filter wheel control program,
such as the one provided here for the IFW3.  When an external filter wheel
option is compiled into xmccd, it will call "set_camera_filter" and 
pass the filter number as stdout.  The filter number and its description will be
visible on the xmccd control panel.  Labels for filters may be changed at run
time by modifying prefs.ccd.


XI.  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 
University of Louisville
Physics and Astronomy
kielkopf@louisville.edu

August 6, 2011






  
