AO Instrument Interface


Instrument software has access to all TCS functions by means of a set of
functions packaged in the IIF library.

Here we propose some additions to the IIF in order to allow instrument
software to control AO specific functions.

The idea is to have an AO specific section in the IIF API, which is as
much as possible independent on the rest of the IIF functions, so that
software developers dealing with instruments which have no AO observation
modes do not need to bother with AO related details in functions calls.

The proposed IIF function will  be a one-to-one mapping of AOS functions
listed in section 2.1 of the document "AOS Functional Description"
(CAN: 486f006b), except for the initialization commands StartObs and
PresetFlat and the Terminate command.  Being the adaptive secondary the
only secondary available, it will be used also by instruments working
in seeing limited mode; because there is no reasons why some instrument
software should issue AO related commands when it will not use AO,
the initialization of the AOS and the presetting of AO subsystem at
the beginning of the observing night should be performed by TCS as part
of the telescope initialization procedure, while the Terminate command
should be issued by the TCS general shutdown procedure.

The instrument software should thus assume that the initial status of
the AOS is ready to start a seeing limited observation. Only instruments
which will use the AO-Sys in some adaptive mode will need to invoke the
related IIF commands.

All AO related IIF calls will be described with reference to the
corresponding AOS commands defined in the document quoted above. They
will have the same input arguments as the commands plus the additional
argument "Side", to specify the affected side of the telescope.


PresetAO
========

Syntax:

   RESULT PresetAO(ao_mode,WFS_sel,SOcoord,ROcoord,Rangle,Mag,Color,
                                                   R0,Wspeed,Wangle,Side)

This call corresponds exactly to the PresetAO AOS command.  Refer to
section 2.1.3 for details.

After calling PresetAO(), the instrument software will need to poll the
related DD  variable in order to  verify the successful execution of
the operation.


AcquireRefAO
============

Syntax:

   RESULT AcquireRefAO(Side)

This call corresponds exactly to the AcquireRefAO AOS command. 
Refer to section 2.1.4 for details.

After the call the instrument software must check the return status and
may retrieve AO parameters from the related DD variables.


RefineAO
========

Syntax:

   RESULT RefineAO(Nmodes,Itime,Nbins,TTmod,F1spec,F2spec,Side)

This call corresponds exactly to the RefineAO AOS command. 
Refer to section 2.1.5 for details.

After the call the instrument software must check the return status and may retrieve 
AO parameters from the related DD  variables.


StartAO
=======

Syntax:

   RESULT StartAO(Side)

These call corresponds exactly to the StartAO AOS command. 
Refer to section 2.1.6 for details.


OffsetXY and OffsetZ
====================

Syntax:

   RESULT OffsetXY(Xoff,Yoff,Side)

   RESULT OffsetZ(Zoff,Side)

These calls correspond exactly to the OffsetXY and OffsetZ AOS command. 
Refer to sections 2.1.7 and 2.1.8 for details.

NOTE: These two calls may also be substituted by more general IIF calls
whose function is to offset the scientific instrument pointing and to
adjust ther scientific instrument focus, respectively, because also non
AO instrument will need these. In this latter case, the IIF implementation
will perform offsetting and focus adjustment in different ways, depending
on current observation mode.


CorrectModes
============

Syntax:

   RESULT CorrectModes(DeltaM,Side)

This call corresponds exactly to the CorrectModes AOS command. 
Refer to section 2.1.9 for details.


Stop, Pause, Resume
===================

Syntax:

   RESULT Stop(Msg,Side)

   RESULT Pause(Side)

   RESULT Resume(Side)

These calls correspond exactly to the Stop, Pause and Resume AOS command. 
Refer to sections 2.1.10, 2.1.11 and 2.1.12 for details.


UserPanic
=========

Syntax:

   RESULT UserPanic(Msg,Side)

This call corresponds exactly to the UserPanic AOS command. 
Refer to section 2.1.14 for details.



FINAL REMARK

It may be useful for instrument software programmers to have available
some additional entry points to interrogate the Data Dictionary with
calls crafted for specific subsets of variables (e.g.: the AO Status).