INDI STV Driver README.stv
2006-09-10, Markus Wildi

1) Credits:

The initial work is based on the program STVremote by Shashikiran Ganesh.
email: gshashikiran_AT_linuxmail_dot_org. The RS 232 initialization was 
programmed by Lukas Zimmermann and parts of the FLI CCD driver are reused
and slightly adapted.

2) Development environment:

I used INDI v 0.4 and kstars 1.2. kstars versions prior to 1.2 do not work 
with image download on PIII 800 MHz running Linux 2.6.16.5-default.

3) Known bugs: 

the connection hangs sometimes. At the startup of the driver
the header or data check sum may fail. This condition is displayed in the
client's log window and on the terminal where the INDI server has been started.
Most of the time this is not a severe error condition. 

If something (foreseeable) goes severely wrong the stv driver does an _exit(1).

The STV does not swallow commands at any speed. At many places there are usleep()
function calls in the code which fit the above mentioned hardware configuration. 
Because they slow down the communication these settings are good for any faster
configuration but may fail on slower/older ones. In case where the communication is 
degraded let me know it.

There are some characters used on the STV's display used in tracking mode. I need
a more or less clear night to translate them to readable characters on the client's
display (as far as I remember the content is still readable). 

4) Feedback: markus.wildi_AT_datacomm_dot_ch

6) ToDo:

Image download: Set the correct window size according the information found in 
image info (e.g. image_info->height).

5) Recommended hardware set up for true remote operation:

Use the STV driver together with the INDI v4ldriver and a video capture 
card to watch the LCD screen on the local computer.

6) Status: 

The INDI STV driver is an experimental release. Experimental means that it may 
hang (despite not often). The terminal where you started the INDI server 
process will sometimes show messages (on stderr) which can only be understood 
if one reads the source code (search for parts of the message).

The current version is basically a mirror of the STV's built in functions. These 
primitives can be used in different ways to enhance the versatility of the STV. 
There are two examples on the tab Settings: 

 1) set current time (UTC) (time may differ, because it takes a while until it
    is set and the seconds can only be set in steps of 15 seconds).
 2) set the ccd temperature

E.g. The STV forgets the time and temperature settings and they must be 
entered at each power up.

A farther reaching example: imagine using the STV remotely and without video 
capture card. The focusing process of the STV might render impossible. I 
think an automated process together with an a INDI focuser driver should do 
that work autonomously.

These two examples are implemented in two different ways. Time set is done 
"blindly". That means the buttons and the rotary knobs (better the software 
equivalents) are used without any feedback from the STV. The ccd temperature 
reads the display and stops when the desired temperature appears.

7) Before you start:

If you want to use the INDI STV driver, please refer to the SBIG STV manual 
first.  The INDI STV driver is basically a remote front end to your fingers 
with additional features.

Please note that the buffers are labeled as 1 to 32. Buffer number 32 is the
LCD screen buffer. Despite SBIG's manual says so, accessible are only buffers
1 through 14 and 32 (at least I found no way to store images e.g. in buffer 
20).

8) Recommended approach:

Put the STV hardware on your desk an connect it to the computer where the 
INDI server and client run. 
First do basic things like changing settings on the STV using the INDI client 
(tab Buttons and Knobs). Compare the results on the STV display with the 
results on the INDI client. The STV's two line display should be always 
synchronous with the INDI client display.
Then try to take an image which is finally displayed on the STV's LCD screen 
and try to download it to the INDI client using the default settings on the 
tab Image Download. 

9) What is not possible:

A mixed operation, that is some commands entered at the STV box and some 
entered via the INDI STV driver, is hardly possible. There is no way how one 
can retrieve the current status of the STV besides monitoring the display of 
the STV.

10) What is not supported:

The meta data of images, e.g. offset, taken in mosaic mode are not read
out currently.

11) Features:

STV's display is reproduced on each tab for convenience.

Connection tab

Set the device and the speed (9600, 19200, 38400, 57600 and 115200).
Start/stop update clients display.

Settings tab

Set the time to UTC.
Set the CCD temperature.

Buttons and Knobs tab

All STV's buttons and knobs are supported. Basically you can use the STV driver 
as if you were sitting in front of the box.
The names and groups are identical to what is printed on the STV's box.
The labels of up/down left/right of the rotary knobs are replaced by Increase and
Decrease in both cases.

Warning: Do not change the STV's speed with File Ops menu. The communication 
will stop. 

Download

Buffers Status: get a quick overview which buffers are used or empty.

The meta information about one image or all images are available and printed in 
the log window.

The buffer on which the buttons One Image (Information and Download) operate on
can be selected.

The download of one or all images can be initiated either in un- or compressed 
mode.

An arbitrary window can be set on the original window. This speeds the download
considerably and is e.g. useful if you want to inspect a single star image.
