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

This software has been developed sith OpenSuse 11.4.  The SBIG library included
here is compatible with this distribution.  In July 2011 SBIG announced on their
website that they will no longer provide updates to the library.  Consequently,
XmCCD support for SBIG cameras will be limited to those included in this version
and most likely not extend to new cameras.  However, the ethernet cameras are
not OS-specific, and it may be that support for them can be incorporated when or
if we have one to test.

The driver should automatically recognize any SBIG camera with a USB interface
which is supported by their Linux proprietary library.  The version of the 
library included here works with  the ST and STL series cameras. One caveat is
the USB system must recognize the camera.  This is handled by the operating 
system, with the assistance of udev configuration files.  The files provided
here work with the ST7, ST9, ST10, ST2000, STL1001 and STL6303 cameras 
available to us. We do not have an STX camera to test.  The software should
work with the STX USB interface.  The STX ethernet interface may be supported
in future versions of XmCCD on request, once we have a camera to test.

Direct support for RGB color with the color variants of SBIG cameras is not 
provided here.  We plan to do that, by generating fits files for the
interpolated R, G, and B images, using the -rgb option of ds9, and exporting
uncompressed tiff and compressed jpg files.  At this time, however, 
color images are treated as gray-scale, and would need post-processing with
ImageJ or other color imaging software.

The CFW and CFWL series of built-in filter wheels are supported, as is the Optec
IFW external filter wheel.  It may be necessary to change the filter wheel
choice in the protocol.h file for the camera.  We leave it with "CFWSEL_CFWL"
in this distributed package because that is the camera we use most often.
However, for the ST10 camera with the CFW10 you may use CFWSEL_CFW10 or
CFWSEL_AUTO.  The latter seems to work well with our camera, although fixing 
the choice may be better if you know what you have.  We create different 
executable versions of "ccd" and "xmtel1" for different camera/filter
combinations and name them "ccd_st10" or "xmtel1_stl" for example,
so there is no confusion in use. Just remember that the software may not
autoselect the right filter wheel for your camera.

The internal autoguider is supported.  The secondary external CCD in the STL
series has not been interfaced with the software at this time. If you have a
need for this, let us know.  We have an auxiliary CCD for an STL camera and
could add support should you need it.

The adaptive optics accessories for ST and STL cameras has been tested with the
driver and is supported. 

The SBIG SG-4 autonomous autoguider is supported in XmGuider, a separate
package.


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 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.1 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 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 
of the source 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. SBIG Library
---------------

There is a version of the driver library in the sbig subdirectory of the
XmCCD package. You should use the included version.  The libsbig directory
in the XmCCD distribution also includes a script for installing the library,
include file, and the usb firmware.  

cd libsbig
./install_sbig

Some older versions of Linux may not work with this library, or may not work
with the rules script that prompts the system to upload firmware to the camera.
The best solution in this case is to update the operating system to at least
Suse 11.1 or equivalent.  An older version of libsbigudrv.a is archived in
libsbig/old should you want to try it.


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_sbig
make
make install

Before the first "make", check the contents of protocol.h to see if it has
your preference for the filter wheel.  You may need to change the default
from the STL internal filter wheel to an external system, or to another SBIG
option.  

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_sbig
make
make install

The protocol files used for xmccd1 are the same as the ones used for indiccd. 
Do not edit the protocol.h file here once you have edited it for indiccd.

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 fan on the camera should
start and its indicator LED should come on.  If the fan and light are on, then
the camera is ready to use.


For a diagnostic you could try 

  lsusb

On our system this is the response when the camera is running:


Bus 004 Device 001: ID 0000:0000  
Bus 005 Device 001: ID 0000:0000  
Bus 001 Device 010: ID 0d97:0101 Santa Barbara Instrument Group SBIG Astronomy 
  Camera (with firmware)
Bus 001 Device 008: ID 04b0:0410 Nikon Corp. 
Bus 001 Device 004: ID 05e3:0606 Genesys Logic, Inc. 
Bus 001 Device 002: ID 05e3:0606 Genesys Logic, Inc. 
Bus 001 Device 001: ID 0000:0000  
Bus 003 Device 001: ID 0000:0000  
Bus 002 Device 002: ID 06c2:0031 Phidgets Inc. (formerly GLAB) 
Bus 002 Device 001: ID 0000:0000  


The identification 0d97:0101 is the one for a camera after the firmware has been
uploaded.  If the upload was not successful, you will see an identification 
such as 0d97:0001, where the second hex number depends on the camera model. 
Other items here are for different devices attached to the USB bus -- in this
case a Nikon camera used for wide field imaging and an RFID tag reader that is
used to encode dome rotation.

In some cases, as root, you may need to upload the firmware from the command
line.  To do this, first find the device address using lsusb.  Then issue a
command similar to this one:

fxload -D /dev/bus/usb/001/002 -I /lib/firmware/sbigucam.hex

where the numbers 001 and 002 identify the USB device found in lsusb, and the
hex file to be uploaded is the one corresponding to your camera (lcam for STL 
cameras and ucam for others like the ST7,8,9, and 10).  


VI.  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.  


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/prefs . 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, put 
the drivers on the command line when callnig the server

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. Filterwheels
---------------

XmCCD is designed to control a filter wheel, and with SBIG cameras it will
detect and use the internal filterwheel if it is available.  You should
select the filter wheel by setting it in protocol.h.  The header file is 
annotated and it is simple to make your choice before compiling the
executable files for your camera.

XmCCD also allows you to select an external filter wheel option on compiling. 
With this, XmCCD will call an external routine and pass a filter number
argument to it, supporting in principle any hardware. 


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 (kielkopf@louisville.edu)
August 6, 2011





  
