INT-AGB-2

Interfaces to the INT
A and G box server

Daniel Matthews

1.1; 1997-02-04

Isaac Newton Group, RGO,
Aptdo 368,
Santa Cruz de La Palma, TF38780 Spain

Telephone (int+) 34 22 405500
Fax (int+) 34 33 405646
Internet drm@ing.iac.es

1 Introduction

1.1 Context

The AGB (acquisition and guidance box) server is a program for the `Solaris' operating-environment that controls the acquisition and guidance box on the INT. The detailed design of the server is described in INS-AGB-3, reference [2]. This document defines the interfaces by which other systems and programs can use the server.

This is a specification of the interface. It is valid for software writers to claim conformity with a specific issue of this document. If the implementation of the AGB server does not match this document, then the software is at fault.

1.2 Overview of interfaces

Much of the detailed behaviour is described in INS-AGB-3 but these details are liable to change. The aspects of the behaviour that can be relied upon are described in section 4 and 5.

The overall architecture of the server is outlined in section 2.

Communicating with the AGB MMS controller is via an RS232 serial link, operating a protocol as described in reference [1]. The specific messages used when communicating with a controller are described in reference [2].

The server runs under the supervision of the general observing system. The interfaces by which the server talks to its parent system are described in sections 4 and 5.

The server requires certain environment variables to find files, and homes for generated files. These are described in section 6.

1.3 References

[1] A&G box technical description LP Technical Manual 23

[2] AGB server detailed design ING/RGO document INT-ABG-3 by Daniel Matthews

[3] Exchangeable optics Interface ING/RGO document *** by Guy Rixon

[4] Interfaces to the INT IDS server ING/RGO document INT-IDS-2 by Daniel Matthews

[5] INT IDS server Detailed Design ING/RGO document INT-IDS-3 by Daniel Matthews

[6] Server services ING/RGO document ?????, by Guy Rixon

[7] Dialogues with the user: General Principles ING/RGO document OBS-TALK-1 by Guy Rixon

[8] Transfer Document ING/RGO document INS-TF-1, by Daniel Matthews

2 Architecture

2.1 System Context

Figure 1. is the context diagram for the AGB server. The primary data and control source is the AGB MMS itself. It is this that controls the position of all the mechanisms and reports the position and status of all mechanisms.

The system is responsive to all kinds of DRAMA transactions. The interface for incoming transactions are defined in section 4. The interface to the talker is defined in reference [7].

The DRAMA parameter database (AGB_parameters) is described in section 5. The archive action causes a FITs packet file to be written to disk. This is described in reference [4]. The environment variables and command line arguments provided by the parent process are outlined in reference [4] and section 6. The low level communications messages between the server and the AGB controller (MMS) are described in the Detailed Design, reference [2]. When the server starts up and when the AGB_INIT action is invoked, the contents of the AGB_Settings file are reloaded - the structure of this file is outlined in section 6.2.

2.2 Communications

The communication to and from the AGB MMS is via one entry point.

For each mechanism there is an update (Update-N) and Action (Action-N) task. When a low level message arrives from the MMS (as a result of the periodic full status request) the message is interpreted and the mechanism status and position is forwarded to the appropriate Update task. This updates the Parameter system and sends a DRAMA Signal (Signal-transaction) to the task. If the task is not active, this message will be ignored.

2.3 Actions

The AGB server has initialisation code, and 16 actions. The detail of the actions is described in section 4. Most of the actions correspond to the movement of a mechanism. The exceptions are the PING and EXIT actions, provided by the srv facility (referecnce [6]), the ARCHIVE action, described in reference [4], and the AGB_INIT action. The AGB_INIT action causes the mountables database (reference [3]) to be reloaded.

Most of the initialisation code is provided by the INS facility, described in reference [4].

2.4 Clients

All except the change_ids and Autoprobe clients are provided by the INS client facility, described in reference [4], with a table defining the implementation in the AGB. A series of soft links are used to provide the different commands for the user.

The change_agb client is provided by a DTCL script. If a new filter slide is required, or a change in the name of one of the filters, this command provides a graphic way of achieving this. Once the change is made, the new filter tray contents are stored in the settings file and the AGB server executes the AGB_INIT action. Next time the server starts up this settings file will be re-loaded, thus ensuring the server always has an up-to-date database of all the filter wheel contents. This is described in more detail in reference [2]

The autoProbe client is used to provide a link between the TCS and the A&G box servers. This is required only when the Autoguider is NOT an array type detector. This is because the guide probes need to move to get the guide star dead centre of the image disecting tube, during the acquire cycle. This task monitors the parameters in the TCS drama task that represent movement requests sent down the inter processor link from the TCS. When these parameters change, the movement is forwarded to the AGB server.

2.5 Mimic

The mimic is defined in reference [4] and described in detail in reference [5]. This is a joint IDS/AGB mimic.

3 Behaviour of the AGB server

This section defines those aspects of the server's behaviour that affect the interfacing. It describes the more complex actions in more detail.

Some of the actions that can be started can take some time to complete. If these actions are obviously going to fail and the user no longer wishes to wait for them to complete, they can be kicked (DRAMA Kick message sent to the action), with no arguments to cause them to terminate. This will not affect the AGB controller, which may continue to move a mirror, or change filter without any action from the server. Therefore it is recommended that this feature be used sparingly and with caution.

Although the AGB can be put into "monitor mode", this has been found to be unreliable. Therefore the full state of all mechanisms is requested every AGBTO_REQSTATUS microsecond (defined in agbInternal.h as 1000000, ie 1 second).

The AGB MMS is mounted on the cassegrain of the telescope. It communicated via an RS 232 port, using the protocol outlined in reference [1]. This serial port can either be plugged directly into the serial port of the System computer, or into a terminal server under control of the system computer.

The exchangeable optics database protocol is used to maintain persistent information of the contents of the filter wheels and calibration lamps. Files containing SDS structures defining the contents of each mechanism are maintained, but are only accessed through the interface described in reference [3]. When the server first starts up, these files are all loaded. If any of these files are changed, the command AGB_INIT should be issued to cause them to be re-loaded.

The server is required to provide a FITs packet describing the state of all the mechanisms. This is provided by the Archive Collection utility, part of the INS facility, described in detail in reference [4].

The TV and autoguider probes movements do not seem to have the status handled correctly by the MMS. So when testing for action/movement completetion, the actual position should be compared to the required position. Some tolerence of the position values should be permitted.

The invocation names chosen for the comparison lamps is stored in the mountables database. This is tested in a case sensitive way and so the names of the requested lamps should be identical to those in the database.

The TV shutter is a separate mechanism to the comparison mirror and lamps, but it is recommended that the TV shutter is only open when there are no comparison lamps on, due to the possibility of damage to the TV intensifier.

4 Command interface

The AGB server is a DRAMA task and its commands are implemented as DRAMA actions, invoked through OBEY messages in the normal way. These actions can be used by DRAMA tasks running on the AGB, instrument control computer or on computers elsewhere on the Internet. Only one AGB server can run on the instrument control computer at any one time.

The AGB server registers with the DRAMA message-system as `AGB'. Note also that case is significant when invoking this program by name. If the host computers for the INT is, say, lpss12, then the AGB server can be addressed as AGB@lpss12.ing.iac.es: this is the fully-qualified task name that would be passed to functions of the DRAMA libraries when connecting to the servers.

The server's actions send one status message when they end and do not send `trigger' messages. Each completion message reports the final status of the action to which it applies but does not describe the state of the sub-system; e.g., a completion message might say that a filter move failed, but it would not say which filter was current at the end of the action. The sub-system state is reported by DRAMA parameters, as described in section 4. Action names are all in upper case: this make it possible to access the actions from an ADAM system. The argument names listed, including the mixed case, should be reproduced exactly in the argument structure passed with the action.

All of the actions that result in mechanisms moving can be kicked during execution. This will cause the action to terminate immediately with an error.

AGB_FLIP changes the position of the flip mirror. The action requires one parameter:

Argument1 (integer) specifies the requested position of the flip mirror. The value can be interpreted using the following definitions is agb.h:

AGB_FLIPFIELD 0

AGB_FLIPSLIT 1

AGB_COMP changes the position of the comparison mirror. The action requires one parameter:

Argument1 (integer) specifies the requested position of the comparison lamp mirror. The value can be interpreted using the following definitions is agb.h:

AGB_IN 0

AGB_OUT 1

AGB_TVS changes the position of the TV shutter. This shutter should not be opened if the comparison lamps are on. The action requires one parameter:

Argument1 (integer) specifies the requested position of the TV shutter. The value can be interpreted using the following definitions is agb.h:

AGB_IN 0

AGB_OUT 1

AGB_ASCF changes the above slit colour filter. This action has one required parameter: