4 USER'S GUIDE

This User's Guide describes the ICS features normally encountered during the usage of ICS. If more detailed information is needed, then please refer to the Programmer's Guide (chapter 7).

4.1 OPERATIONAL STATES

When no ICS processes are running then ICS is in the OFF state. After the start-up of ICS processes the ICS state becomes LOADED which means that the system is ready to receive commands.

When the STANDBY command is entered the various SW devices enter the STANDBY state and the global state changes to STANDBY.

When the ONLINE command is entered the motors perform the hardware initialization and after a successful initialization the ONLINE state is entered. The global ONLINE state is only entered when all enabled SW devices are ONLINE. The ONLINE state is required to perform any action commands on instrument functions such as SETUP.

At start-up of the ICS WS processes the state of the LCU is queried and the ICS WS process aligns itself with the state of the LCU. This is why starting the ICS WS might result e.g. in becoming ONLINE immediately.

4.2 SIMULATION

ICS distinguishes between three level of simulation, as described in Table 1.

Table 1 ICS simulation levels
MODE	Description
LCU_SIM	The control over the whole hardware is disabled The LCU sw is simulated at Workstation level
HW_SIM	The control over some parts of the hardware is disabled The missing parts of the hardware are simulated at LCU level
NORMAL	The control over the whole hardware is enabled

The level used to observe at the telescope is NORMAL. However there might be situations, in a laboratory or just in a sw development environment, where the complete hardware or part of it is not available. The LCU_SIM level is used when neither the hardware nor the ICS LCUs are available. The HW_SIM level is used when at least one ICS LCU is available, but the whole or part of the hardware is not available. Keyword INS.CON.OPMODE in the xxmcfgSTART.cfg file is used to specify if LCUs are available or not.

The simulation level is always indicated in the FITS header files generated by ICS through the keyword HIERARCH ESO INS SOFW MODE.

Furthermore, whenever the hardware of a device is totally or just partly simulated, it has also to be indicated in the FITS header through the keyword parameter SWSIM. For example, if the hw of the device filter wheel (keyword INS.FILT1) is simulated on the LCU, the following line must be present in the FITS header:

Note: The degree of simulation provided in LCU_SIM is supposed to satisfy the needs of Instrumentation applications developers, in absence of LCUs. It has to be pointed out however that the actual behavior is a simplified sub-set of all what the LCU sw actually does. In particular, several OLDB attributes associated to ICS devices, such as available, simulation, state (see also section 4.3.2) which in NORMAL or HW_SIM are regularly updated by the LCU sw, in LCU_SIM are not updated. It is therefore recommended, whenever LCUs are available, to use them.

4.3 ICS SOFTWARE DEVICES

A instrument has several hardware components. As a general rule, each hardware component (or a set of related hardware components) is controlled on the LCU via a software device. Each software device is identified by an acronym (e.g. BFIL: blue filter wheel) and has a FITS prefix assigned to it (e.g. INS.FILT1, i.e. all FITS keywords related with the blue filter wheel start with `INS.FILT1').

The software devices of an instrument are listed in the Instrument ICS User's Manual (see [23] as example).

4.3.1 Software Device States

Each device controlled by ICS can be in one of the states described in Table 5.

Table 2 ICS device states
STATE	Description
OFF	The device server is not running. The device is powered off.
LOADED	The device server is running. The device is not initialized or under handset control or powered off. After an LCU reboot, all the ICS devices are in this state (sensors can be placed automatically in state ONLINE after an LCU reboots).
STANDBY	This is the normal day-time state. The definition of stand-by must be configured in the OLDB. The default is: · Motors are powered off. · Lamps are off. · Shutters are closed. · Sensors are periodically monitored.
ONLINE	The device is initialised. When changing from STANDBY to ONLINE, devices which were already initialised should not be re-initialised (i.e. it must be possible to go back and forth between ONLINE and STANDBY without having to re-initialise the device every time). It is possible to perform action commands, such as SETUP.

The ICS global state reflects at any time the state of its devices, in particular the global state corresponds to the lowest among the current device states (e.g. all devices are ONLINE but one, which is LOADED: the ICS global state is LOADED)

Each device has a substate. The substate is normally IDLE, except when a command is executing.

· IDLE: ICS is ready to accept and execute a command.

· BUSY: A command is being executed. Apart from STOP all other commands will be rejected until the current command was executed.

4.3.2 Software Device Modes

The software device OLDB point has several attributes reporting the modes of the device. It is important to consider these attributes as read-only. A mode should only be modified updating the instrument configuration or calling the corresponding commands described below.

1. handset: reports when a device is in handset mode.

2. simulation: reports the simulation mode of the device. It is set with commands SIMULAT and STOPSIM.

3. The enabled and fixed modes and therefore the ENABLE, DISABLE and FIXPOS commands are not supported (see [7]).

4.4 PANELS

Instrument specific ICS panels are described in the specific Instrument ICS User's Manual.

4.5 COMMANDS

All applications and panels should communicate with ICS sending commands only to the ICS front-end server xxiControl. This server accepts the commands listed below¹.

Table 3 State Commands
Name	Arguments	Description	State
OFF	-function	Bring ICS to the LOADED state	All
STANDBY	-function	Bring ICS to the STANDBY state	All
ONLINE	-function	Bring ICS to the ONLINE state	All
STATE	-function -global	Return the device or global state	All

Table 4 Software Device Commands
Name	Arguments	Description	State
SETUP	-function	setup the instrument	O
EXPSTRT	-path	do all ICS actions related to the start of an exposure on the specified path (for the possible values see 7.5.5.2)	O
EXPEND	-path	do all ICS actions related to the end of an exposure on the specified path (for the possible values see 7.5.5.2)	O
STOP	-function	Stop immediately all ongoing movements.	All
STATUS	-function -header -dumpFits	Return the current device status With options -header -dumpFits <file> a partial FITS header file, with all HIERARCH ESO INS keywords, is created in $INS_ROOT/SYSTEM/DETDATA	S, O
SIMULAT	-function	Enable device HW simulation on the LCU.	All
STOPSIM	-function	Disable device HW simulation.	All

Table 5 Misc. Commands
Name	Arguments	Description	State
DEBUG	-level -log -verbose	Set the process debug level, logging and verbose mode.	All
VERSION	-	Return the software version	All
EXIT	-	Terminate the process	All

The default for many common INS commands is -function all (see [2]). The intuitive meaning of `all', is to forward the command to all functions of the instrument. In practice however, this is not always useful.

· Sensor devices are excluded from commands STANDBY and OFF when they are in state ONLINE and the INS.CON.ONLINE config. keyword is true (see section 8.9.2). In this case, sensor devices are only addressed when they are explicitly mentioned in the -function parameter.

· The SIMULAT command is sent only to devices that are not in simulation.

· The STOPSIM command is sent only to devices that are in simulation.

· Command STATUS is rejected by devices in state OFF, therefore these commands are forwarded only to devices in states STANDBY or ONLINE.

4.6 ICS SELF-TEST

Every ICS must provide a self-test procedure to validate the whole package (see [24]) e.g. whenever a new release is installed or after modifications to the Instrument configuration.

Base ICS provides a utility (called ic0SelfTest), which implements this functionality.

It takes information (INS.TEST*.*, see section 8.16) from the configuration file xxmcfgINS.cfg in order to determine which sequence of actions/commands it has to execute. Normally a complete self-test should include the following:

· Exercise a sequence of SETUP commands to verify that all software device position correctly and with the highest possible degree of parallelism, i.e.:

· As many devices as possible should be moved in parallel

· All named positions (if any) for every device must be addressed

· A meaningful sub-set of discrete positions, covering the whole valid range, must be addressed, for those devices positioning over a continuous range.

· Exercise the STATUS command, including option -header -dumpFITS for the creation of the partial FITS header file (see 4.5)

· Exercise EXPSTRT and EXPEND for all possible values of the parameter path

An example of configuration keywords for ic0SelfTest is available in xxmcfgINS.cfg for the Template Instrument.

The ICS processes may understand some additional commands: if they are not listed here, then they should not be used.