7 PROGRAMMER'S GUIDE

This chapter is intended to help programmers, who already dispose of a working ICS prototype and intend to complete its implementation by adding instrument specific features.

It is assumed here that icb has already been properly installed. See chapter 10 for more information on this subject.

It is also assumed that the environment variables, as defined in section 10.2.2, are properly defined.

7.1 OPERATIONAL STATES

The state is reported in the attribute <alias>XXXX:ICS:PROCESSES:WS:icsControl.state.

7.1.1 Change Operational State

Table 6 describes the commands to be sent to change the ICS global state.

Table 6 State transition commands
To	OFF	LOADED	STANDBY	ONLINE
From	OFF	LOADED	STANDBY	ONLINE
OFF	---	startup script xxinsStart -proc ICS	---	---
LOADED	shutdown script xxinsStop -proc ICS	---	STANDBY	ONLINE
STANDBY	shutdown script xxinsStop -proc ICS	OFF	---	ONLINE
ONLINE	shutdown script xxinsStop -proc ICS	OFF	STANDBY	---

7.1.2 Operational Sub-state

1. idle. Last action was completed successfully. No command is being executed. ICS is ready to accept and execute a new command.

2. busy. A command is being executed. Every incoming command will be rejected. The only exception is the STOP command, which will be always accepted and executed immediately.

7.2 SIMULATION

7.2.1 Set or Change Simulation Level

The simulation level cannot be changed online. It has to be set to the wanted value (see section 4.2 for the set of possible values and their meaning) in the xxmcfgSTART.cfg file before starting ICS.

Whenever the ICS LCU part is used (simulation level NORMAL or HW_SIM), the simulation mode of each software device is reported in the OLDB point (on the LCU and also scanned to the WS) of the device, e.g. in the attribute: <alias>FILT1.simulation.

7.3 DEBUG LEVELS

7.3.1 Set or Change Debug Level

The command DEBUG is used to set the debug level (1-5), to specify if debug messages should be logged and to set the verbose mode of a process.

7.4 ICS SOFTWARE DEVICES

Each ICS software device has its own state, modes and status. The ICS WS front-end process reports a global operational state based on the states of the individual software devices managed by the LCUs.

7.4.1 Software Device States

The software device states are described in section 4.3.1. These states are reported in the corresponding state attribute in the device point (e.g. <alias>FILT1.state).


State	Standard Devices¹	Special Devices
OFF	0	1: lccDEV_OFF
LOADED	1	2: lccDEV_LOADED
STANDBY	2	3: lccDEV_STAND_BY
ONLINE	3	4: lccDEV_ON_LINE

Standard devices use a different enumeration to keep back-compatibility with instruments based in ic0.

7.4.2 Software Device Substate

Each device has a substate reported in the attribute substate (e.g. <alias>FILT1.substate). The substate is normally IDLE, except when a command is executing.

· 4: SHUTTING_DOWN (in the Stand-by to Loaded state transition)

7.4.3 Software Device Error Flag

The attribute is set at the end of the device movements to indicate if the action was successful or not. In this case the error attribute is set to value ERROR_WARNING.

State transitions from ONLINE to STANDBY, and from STANDBY to LOADED, are always made, regardless if errors are encountered (otherwise it would not be possible to e.g. disable a faulty device). However in this case the error attribute is set to value ERROR_SERIOUS and state transitions from LOADED to STANDBY, or STANDBY to ONLINE, are rejected until the error flag is manually reset or the LCU is rebooted.

7.4.4 Software Device Status

The status of a software device is distributed among several attributes, depending of the type of device. To have a uniform way to access the status of a software device, the individual status values are copied to a status vector. This status vector is the only status item in the software device point that should be regarded to be public.

The individual entries depend of the software device type. E.g. the status vector of a icbMOT_OPTI software device contains the following values:


Index	icbMOT_OPTI
0	element name
1	offset [deg].
2	element id
3	element no. [0..n-1]
4	element type
5	position [Enc]
6	offset [Enc]

The status is a vector of strings to be able to report any value type. The vector is updated at the end of a movement (not during a movement, this avoids loading the LCU with scanning update requests when several functions are moved simultaneously) and in regular intervals by the ICS device monitor task.

The GETCONF command (sent directly to the LCU server process) is used mainly during testing and maintenance. It returns the current status and the configuration of the device. If the allElements flag is given, then the elements of all wheel positions are reported; otherwise only the element in the light path is described (if the component does not have several elements, then the flag is ignored).

7.5 ICS WORKSTATION PART

· For software device commands (see section 4.5 Table 4), involving FITS keywords, split this list and forward to each LCU only the sub-set under its responsibility.

· On request (command STATUS -header -dumpFits <filename>), collect status information from the LCUs and store it into a partial FITS header file.

· Simulate (in a simplified way, see section 4.2) the behaviour of the ICS LCU part, whenever LCUs are not available.

This basic functionality is provided by the ic0Control (ICS front-end) and ic0SimControl (LCU simulator) applications.

Instruments, which do not have any special need and are satisfied with the default behavior provided by icb are invited to use these two applications as they are.

The remaining part of this section and sub-sections describe what to do if an application needs to introduce special features in the ICS front-end process (it is assumed that the LCU simulator does not need to be changed in any case).

4. Execute a special action associated to a particular keyword, passed with a device command (typically SETUP).

5. Group a set of keywords, possibly associated to different ICS software devices, into a single keyword, to simplify the interface with the higher-level software (OS)

6. Perform complex setups, requiring a particular sequential order, e.g. because the devices involved are interlocked or may collide.

The following sub-sections give instructions and examples on how to implement these features.

For a better understanding, it is necessary first to have a look at the purpose of the classes involved and their dependencies. They are shown in Figure 2.

· ic0CtrlMAIN_HANDLER. This is the only class, which is directly instantiated within the main body of ic0Control. It provides general services, such as setting default debug levels, parsing the runstring for options. It is not supposed to be sub-classed, except when a sub-class of ic0SERVER is used.

· ic0SERVER. It provides the core of the ICS WS part functionality, in particular all callbacks for commands/replies.

· ic0INS_MODEL. An object of this class is used by ic0SERVER. For each ICS software device, it creates an object of class ic0INS_DEVICE (or sub-class) and uses these objects to deal with short-FITS keywords.

· ic0INS_DEVICE. It is the base class for all WS objects in ic0INS_MODEL associated to ICS software devices. The specialised sub-classes currently available are:

· ic0INS_ASSEMBLY. It is a sub-class of ic0INS_DEVICE, but there is no one-to-one relationship with a ICS software device. It is used to create associations of keywords for the purposes described in section 7.5.5. Two specialized assembly sub-classes are defined:

· ic0INS_MODE to treat the keyword INS.MODE (Instrument Mode).

· ic0INS_PATH to treat the value of option -path for commands EXPSTRT/EXPEND.

7.5.1 Modify the callback for a specific command/reply

Most of the callbacks to commands and replies implemented within the ic0SERVER class are quite long and complex. On the other hand, sometime ICS WS front-end applications need to change only slightly the default behavior, and in most of the cases this should be possible by overloading specific methods, rather than the complete callback.

It is therefore recommended to consider the replacement of the complete callback as the extreme solution, to be adopted only if, after consulting the ESO sw responsible, no more appropriate one is found.

· Callback method must be overloaded (see e.g. StatusCB in xxiSERVER.C)

· a sub-class of ic0CtrlMAIN_HANDLER must be created (see xxiCtrlMAIN_HANDLER.C)

· Method NewServer must be overloaded, in order to create and use an object of the sub-class of ic0SERVER, instead of ic0SERVER itself (see xxiCtrlMAIN_HANDLER.C).

7.5.2 Attach a dedicated callback to OLDB events.

ICS WS front-end applications may need to do a specific action whenever the value of an attribute in the OLDB changes. In this case the following has to be done:

· Method AttachDbEvents must be overloaded. Within this method, all the calls necessary to attach to the event and associate a specific callback to it must be done (see xxiSERVER.C)

· A OLDB attribute callback must be implemented and added to the class methods (see DbEvtCB in xxiSERVER.C).

· a sub-class of ic0CtrlMAIN_HANDLER must be created (see xxiCtrlMAIN_HANDLER.C)

· Method NewServer must be overloaded, in order to create and use an object of the sub-class of ic0SERVER, instead of ic0SERVER itself (see xxiCtrlMAIN_HANDLER.C).

7.5.3 Attach a dedicated callback to a Timer

ICS WS front-end applications may need to do a specific action at periodic intervals. In this case the following has to be done:

· Method AddTimers must be overloaded. Within this method, all the calls necessary to create a timer and associate a specific callback to it must be done (see xxiSERVER.C)

· A timer callback must be implemented and added to the class methods (see TimerCB in xxiSERVER.C).

· a sub-class of ic0CtrlMAIN_HANDLER must be created (see xxiCtrlMAIN_HANDLER.C)

· Method NewServer must be overloaded, in order to create and use an object of the sub-class of ic0SERVER, instead of ic0SERVER itself (see xxiCtrlMAIN_HANDLER.C).

7.5.4 Execute a special action associated to a particular keyword

By default, each keyword received by the ICS WS front-end process as part of command (e.g. SETUP) parameters is forwarded to the LCU responsible of the related device. This is the behavior implemented in the ic0INS_DEVICE class and its sub-classes.

ICS WS front-end applications may need to do a specific action whenever a particular command and/or keyword is processed. In this case the following has to be done:

· a sub-class of the appropriate ic0INS_DEVICE sub-class (see Figure 2 for all existing sub-classes) must be created. E.g. if the keyword is INS.LAMP2.ST, ic0INS_LAMP must be sub-classed.

· The new class must be registered in the application. This is done in the file containing the main body by adding a RegisterStorable instruction. For example, if the new class is called nniINS_LAMP and the keyword needing special treatment is INS.LAMP2.ST, the following lines must be added in the file nniControl.C:

7.5.5 Assemblies

ICS Assemblies are defined and used to fulfill possible needs of WS front-end applications, in relationship with the handling of commands and set of keywords.

An ICS front-end application does not need to define or add assemblies. However, whenever it wants to do it, they must be defined in the configuration file (see INS.ASSEMBLY* in xxmcfgINS.cfg and section 8.15 for more details on configuration aspects and options).

1. Simplify the interface to OS, by grouping a set of pairs keyword+value into a single one (SETUP). Example:

INS.ASSEMBLY1.VAL1 "INS.LAMP1.ST F INS.SHUT1.ST F INS.MIRR1.NAME TELESC"

INS.ASSEMBLY1.VAL2 "INS.LAMP1.ST T INS.SHUT1.ST T INS.MIRR1.NAME SPHERE"

SETUP -function INS.LAMP1.ST T INS.SHUT1.ST T INS.MIRR1.NAME SPHERE

2. Simplify the interface to OS, by grouping a set of keywords into a single one (STANDBY, ONLINE, SIMULAT, STOPSIM, STATUS). Example:

INS.ASSEMBLY1.VAL1 "INS.LAMP1 INS.SHUT1 INS.DROT INS.DPOR INS.MIRR1"

SIMULAT -function INS.LAMP1 INS.SHUT1 INS.DROT INS.DPOR INS.MIRR1

3. Perform complex setups, requiring a particular sequential order, e.g. because the devices involved are interlocked or may collide. The steps in the sequence are separated by comma. Example:

INS.ASSEMBLY1.VAL1 "INS.LAMP1.ST T INS.OPTI1.NAME OUT, INS.OPTI1.NAME IN, INS.SHUT1.ST T"

it converts it and sends to the LCU(s) the sequence of commands:

For each defined assembly, the last value set with a SETUP command is stored in the OLDB attribute ICS:ASSEMBLIES:status(i) (bytes32), where the index i corresponds to the assembly index in the configuration file (INS.ASSEMBLYi).

Such a value is also stored in the FITS header file (STATUS -header -dumpFits <filename>), provided the keyword INS.ASSEMBLYi.HEADER exists and is set to T (see also 8.15)

7.5.5.1 Mode

The class ic0INS_MODE is a special assembly, dedicated to the handling of the keyword INS.MODE (Instrument Mode).

All ICS WS front-end applications are responsible to write the keyword INS.MODE in the FITS header (mandatory). For this reason, the INS.ASSEMBLYi.HEADER flag for INS.MODE is by default set to T.

The meaning of Instrument Mode, in terms of setups, can be very different from Instrument to Instrument:

1. All actions related to the setting of INS.MODE are done on the LCU and the LCU takes care of returning, among others, also the value of INS.MODE for the FITS header.

In this case no assembly INS.MODE has to be specified in the configuration file.

2. The handling of INS.MODE is done only on WS and consists of just adding its current value to the FITS header file produced by ICS.

In this case, the assembly INS.MODE has to be specified in the configuration file, as follows:

the meaning of this setting being "whenever the INS.MODE keyword is processed, no matter which value, do not send it to the LCU".

3. The handling of INS.MODE is done partly on WS and partly on LCU, in the sense that the pair INS.MODE+value has to be converted into a set of pairs keywords+value, to be forwarded to the LCU for processing.

For the particular case of INS.MODE, the WS conversion is not supposed to be done by ICS, but by OS, i.e. ICS is supposed to receive from OS already the appropriate set of pairs kewyors+value, which it has to forward to the LCU. In addition to this, it receives also the pair INS.MODE+value for the FITS header.

The settings needed to cope with this situation is the same as described at point 2. above.

7.5.5.2 Path

The class ic0INS_PATH is a special assembly, dedicated to the handling of the parameter -path associated to commands EXPSTRT/EXPEND.

All ICS WS front-end applications are responsible to write the keyword INS.PATH in the FITS header (mandatory). For this reason, the INS.ASSEMBLYi.HEADER flag for INS.PATH is by default set to T.

In general, the actions ICS has to take (if any) at the beginning and at the end of an exposure depend on the characteristics of the exposure and in particular on the devices involved in it. In particular, if an Instrument has more than one scientific camera, the set of devices along the light path is different for each camera.

Purpose of the -path parameter in EXPSTRT/EXPEND (and therefore of the INS.PATH assembly) is to define which devices are involved in the exposure, such that the DevTrigger method of each object associated to these devices is called for the appropriate action (see 7.5.4).

By default, the DevTrigger method of ic0INS_DEVICE and sub-classes do nothing in conjunction with EXPSTRT/EXPEND. Therefore, if an ICS WS front-end application does not have to do any particular action at start and end of an exposure, nothing has to be done neither at code nor at configuration level.

If instead some special action is needed, then the INS.PATH assembly has to be defined in the configuration file. Example:

Call the DevTrigger method for all devices included in the assembly INS.INFRARED

Call the DevTrigger method for all devices included in the assembly INS.PRESIILT and for device INS.MIRR2

Call the DevTrigger method for all devices included in the assembly INS.OPTICAL

An example of DevTrigger method overloading for the purpose of taking a special action in connection with EXPSTRT/EXPEND is given in xxiINS_ANALOG.C

7.6 COMMANDS

The typical sequence of commands sent by an Instrument Observation Software (OS) to ICS, once the whole Instrument (including ICS) is ONLINE and ready to execute exposures, is:

SETUP [-file <filename.ins>] -function <keyword1> <value1> .... <keywordn> <valuen>

7.7 PUBLIC ONLINE DATABASE ATTRIBUTES

The complete OLDB of ICS should be regarded as read-only by external software. The OLDB is updated according to the issued ICS commands. Status data can be retrieved from the OLDB from the attributes listed in the above sections. All other attributes should be regarded to be private.

7.8 CONFIGURATION AND OPERATIONAL LOGS

Operational logs are normally performed by the LCU ICS processes whenever an action on the hw, changing the instrument setup, has been started and completed.

7.9 INTERFACES

7.9.1 Human interfaces

The ICS module is normally used programmatically from higher level sw, like OS, simply by sending commands to ICS. On the other hand, specially for engineering purposes, it is desirable to work with ICS stand-alone, and therefore have GUI panels interacting directly with ICS, allowing to test single functions or groups of functions, without needing to have neither OS nor MS on top of ICS.

Examples (not yet available) of an ICS stand-alone panel can be found in the module xxipan.

The ICS panels must all be built with the VLT panel editor providing the same look & feel as other VLT applications.

For motion control the Motor Engineering Interface (motei) is used as GUI to test motors (see [15]).

7.9.2 Hardware interfaces

All hardware interfaces to ICS devices are on LCU: the WS does not access directly any piece of hardware.

icb supports only devices using standard hardware components. In order to use as much as possible the code provided within icb, instrumentation should use standard hardware components wherever possible.

7.9.3 Software interfaces

7.10 ERROR DEFINITIONS

The icb software uses the standard mechanism defined and provided by the CCS error system to log and return error information to other applications.