SOFTWARE INTERFACE

The ATCS Interface

The Auxiliary Telescope Control System software interfaces toward the VLTI Interferometer Supervisor Software are essentially based on the already existing VLT Unit Telescope TCS interfaces [AD10], since the two systems must behave as much as possible in the same way from the point of view of higher level control.

In this document we will describe only the basic concepts and the specific list of commands and database items that are implemented on the Auxiliary Telescopes. For more details on the way interfacing programs have to be written, man pages of the API classes and of commands, look at the VLT TCS User Manual [AD10].

TCS for any telescope of the VLT family is composed of a lot of software modules, each of them consisting of one or more processes. To unify and simplify the access from users to the TCS functions any telescope exposes a public TCS Interface, represented by the atif module.

The atif module is responsible for providing the central and only command interface between external users and the TCS. The VLTI Interferometer Supervisor Software is the most typical high level user for the VLTI Auxiliary Telescopes.

The VLTI Supervisor Software user processes communicate with the ATCS by sending commands to and receiving replies from the atif. The atif internally dispatches the commands to the responsible TCS processes, receives their replies and passes them back to the caller.

The atif module uses all functionality of the tif module, but has a specific CDT file and special database clasess.

In order to use atif also tif is required.

To enable multiple read access to TCS public data, a Data Query Library is provided which is linked to the user process and thus is not subject to the booking system. Also a public Event Configuration Library is provided to attach events to TCS data items. These libraries are described in section Application Programming Interface.

Commands

This section gives a list of all TCS commands available up to now, together with a brief description. See the VLT TCS User Manual [AD10] for a detailed description of each command and for sample programs.

The following table alphabetically lists the telescope control commands. On top of these TCS commands, the tif control process accepts all the usual VLT standard commands and a small set of specific commands used for maintenance purposes.

The complete set of commands accepted by the atif control process is described in the CDT in appendix

Units and coordinate systems for command parameters follow VLT conventions.

These are perhaps not the ones some users would expect, or might be different to what is used in other contexts (like FITS Headers). Please, make sure that you always check units and conventions in the Command Definition Table.

This document describes the interface between AT and ISS, i.e. all the interfaces needed to control the ATs for VLTI observations. TIF in itself will probably also have more commands, used to control the telescope not for pure VLTI coordinating purposes. This anyway does not include operations performed by the operators on control panels. For example operating the enclosure is done via a dedicated AT control panel, that uses internal AT commands, not defined in tif. This is because we do not want enclosure commands to be public for other applications than the operator control panels and AT internal procedures.

tif is a highly flexible piece of software that allows publishing a set of TCS commands and data.
Usually a subset of all available TCS commands is made publicly available. The list can be easily changed and extended or reduced.
ISS will interact with ATCS only through atif. Only data and commands relevant for ISS will be published by ATCS.
Further data and access can be retrieved by the operator via ATCS specific user interfaces, e.g. check of temperatures etc.

Telescope Commands

Command	Description
CLRSTP	Clear ready SETUP file with default values
DETCGS				Detect guide star and offset telescope to center it.
GETINS				Get currently selected instrument
GETINSD				Get instrument configuration parameters
OFFSADG		Issue an RA/DEC combined offset step
OFFSGUV				Offset of the guide probe in UW.
ONECAL				Active Optics calibrated mirror corrections, based on current telescope altitude.
OPTCGS				Optimize strap guiding loop.
PRSCOOR		Preset telescope to given RA/DEC coordinates (tracking)
PRSNAME		Preset telescope to named fixed position
RESUME				Resume Coude guiding after a suspend
SELINS				Select the logical observing instrument
SETINSD				Set instrument configuration parameters
SETUP		Define a new setup configuration (standard format, as defined in INS Common Software Specification [RD10], for FITS keywords see section FITS Header Data)
STOPCAG		Stop autoguiding. Stops normal autoguiding (using FAS) or field stabilisation (using STRAP)
STOPCHP		Stop chopping
STOPTRK		Stop tracking and stay at actual position
STRTCAG		Start autoguiding. Starts normal autoguiding (using FAS) or field stabilisation (using STRAP)
STRTCHP		Start chopping immediately or at a given time in the future
SUSPEND				Temporary suspend Coude' guiding

 

Sending commands to TIF processes

• To have ATCS or ATCS Simulation Package installed and configured (see VLT TCS User Manual [AD10])
• Environment variables properly set (see VLT TCS User Manual [AD10])
• A running environment with ATCS or ATCS Simulation database branch (see in particular section Using the TCS Database and Event Interface Library )
• A running ATCS.

Application Programming Interface

• The Data Query Library retrieves ATCS data items. This includes functions to retrieve FITS header keywords.
• The Event Configuration Library attaches events to ATCS data items
• The two data libraries are combined in the tifLibs library files (both static and shared versions) under $VLTROOT/lib and can be linked to an application in the usual way (see man-page of the vltMakefile). The sources need to include the tif.h header file to access library functions. See VLT TCS User Manual [AD10] for man-pages of the libraries and for a sample program.

Data Query Library

Named Data Items

FITS header data

TCS FITS Header Keywords

Event Configuration Library

Database Events

Using the ATCS Database and Event Interface Library

• To have ATCS or ATCS Simulation Package installed and configured (see VLT TCS User Manual [AD10])
• Environment variables properly set (see VLT TCS User Manual [AD10])
• A running environment with ATCS or ATCS Simulation database.
• The code should be written in C++ or at least compiled with the C++ compiler, i.e. the files should have the .C (capital C) filename extension. For more details on how C and C++ code interact, refer to the eccs [AD 07] and evh [AD 09] user manuals.
• The Makefile must contain proper definitions for the TARGET_TCS to be built.
• The library tifLibs must be linked with the code. A typical VLT C++ application requires also the following set of libraries: evh eccs fnd C++ CCS.
• If tifGetFitsStart() and tifGetFitsEnd() are used also the following libraries must be linked with the code; oslx slx misc tcsVcc msw .
• The include file tif.h contains all the necessary definitions and function prototypes. VLT TCS User Manual [AD10]
  contains three complete and working sample programs, two using the Data Query Library and the other one using the Event Configuration Library.

Online Database Access Classes

The atif module provides a set of public on-line database classes to allow access to ATCS public data items via the on-line database instead that via the tif Data Query Library.

The class atifTCS_PUBLIC can be instantiated in any user database to provide a local image of the ATCS public data items. This class is used when the TCS database, real or simulated, is NOT in the same environment as the user database. In this case, the scan system is used to update the user database with values from the ATCS environment (real or simulated).

The class atifTCS_LOCAL has the same structure as atifTCS_PUBLIC (it is a subclass) and provides the same items, but can be instantiated in the same environment where TCS itself is running, i.e. when simulated TCS data are a part of the user database. In this case, the items are updated using the calculation engine, instead of the scan system.

These classes have been implemented to provide access to ATCS data for UIF instrument panels and Sequencer scripts, while C and C++ applications should use the tif Query Library.

For performance reasons, not more than one instance of the classes should be used in each environment.

Structure of the atifTCS_XXX public on-line database classes

The atifTCS_PUBLIC on-line database class (see the man page for details) is structured in sub-points that group the public items by category.

This has been done in order to allow a more structured access to the items themselves and to optimize performance on the update of the items, that is based on the RTAP calculation engine.

What follows is the structure of the class:

atifTCS_PUBLIC

tcsState - Global TCS state information

tcsState - TCS global state, as in Mode Switching

tcsSubstate - TCS substate, as in Mode Switching

track - TCS tracking flag (0/1)

domeStatus - Current dome Status

times - Time items

lst - Local Sideral Time

utc - Universal Time Coordinated

coord - Target coordinates

ha - Target actual Hour Angle

ra - Target actual RA

dec - Target actual declination

ra2000 - RA at mean place of J2000 in HHMMSS

dec2000 - dec at mean place of J2000 in DDMMSS

ra 2000deg - RA at mean place of J2000 in deg

dec2000deg - dec at mean place of J2000 in deg

alt - Telescope altitude

az - Telescope azimuth

prltic - Actual parallactic angle

track - Tracking parameters

airmass - Actual airmass

dvelra - Differential velocity RA

dveldec - Differential velocity dec

remtime - Remaining tracking time

remlimit - Remaining tracking time limit

trackingLost - Event flag for lost tracking

remTimeLow - Event flag for low remaining trk. time

coude - Coude parameters

state - Guide state

guidingStatus - Guide status

guidingMode - Guide status

trackingState - Tracking state

trackingStatus - Tracking status

RA2000 - RA of current guide star J2000 (HMS)

DEC2000 - dec of current Guide Star J2000 (HMS)

mag - Guide star magnitude

wavelen - Guide star wavelen

probeRA2000 - RA of current guide star J2000 (HMS)

probeDEC2000 - dec of current Guide Star J2000 (HMS)

probeInPos - Guide probe in position

guidingLost - Event: Unexpected loss of guiding

trackingLost - Event: Unexpected loss of tracking

m2 - M2 parameters

focuValue

info - General information

telescop - Telescope name

version - TCS software version in use

installed - TCS software installation date

oper - Telescope Operator name

foculenCO Focus length coude

focuscaleCO Focus scale coude

site - Site information

longi - Longitude

lati - Latitude

level - Height above see level
station - station id string

chop Chopping configuration

status - chopping status (active or not)

startTime - starting time (ISO string)

stopTime - stop time (ISO string)

freq - frequency

throw - amplitude

posOptImage - optimal position for image

peakValleyRatio - peak to valley ratio

telPointingAxis - telescope pointing axes

posAng - chopping angle

offsetChop - chopping offset with respect to center position

asm - Astronomical site monitor

seeing

windspeed

winddir

For more information about the meaning of the items, their units and their availability, see the Data Query Library and in particular Named Data Item Table .

Note: Add location (station), local seeing (mean, median, max & min), observatory and local coherence time (mean, median, max & min) of the AT.

 

Using the atifTCS_PUBLIC database class

1. Configure the ATCS database to allow scanning from the remote user environment.


To this purpose it is necessary to add a scan device for the environment in the ATCS database.
For example, add the following lines in the USER.db file of the ATCS environment:
POINT "<VLT scan dev" ccs_config:scan\ config:LAN:wsIns
BEGIN
ALIASwsIns
END

2. Configure the user database to perform scanning from the ATCS environment.


To this purpose it is necessary to add a scan device for the ATCS environment in the user database.
For example, add the following lines in the USER.db file of the user (instrument) environment:

POINT "<VLT scan dev" ccs_config:scan\ config:LAN:wsTcs

BEGIN
ALIAS wsTcs
END

3. Add an instance of the atifTCS_PUBLIC class anywhere in the user database. The Makefile must contain proper definitions for the TARGET_TCS to be built (see VLT TCS User Manual [AD10])
4. Configure the scan system by using the atifTCS.scan scan configuration file.


See the man page for details on the command.
If a standard ATCS configuration is used and if the environment variables are properly set, it is only necessary to pass the "-p" parameter with the symbolic address of the instance of the atifTCS_PUBLIC class.

5. In order to minimize the resources used by the scan system, it is suggested to disable the scan links for all the items not used, by using the CCS Engineering Interface tools or writing a proper script for this purpose.

Using the atifTCS_LOCAL database class