8 CONFIGURATION GUIDE
8.1 INTRODUCTION
The instrumentation software has a special software module (xxmcfg) that contains all configuration files related to the instrument, and therefore also to ICS. This software module allows to keep the complete configuration in one central location and under strict configuration control.
The configuration files contain a complete description of the instrument:
The generic WS and LCU servers of Base ICS configure themselves from the contents of these files.
This chapter describes the ICS configuration in detail and explains how to update and test configuration changes.
8.2 ICS CONFIGURATION FILES
The ICS configuration is located in a set of files stored in the xxmcfg module (xxmcfg/config):
· xxmcfgCONFIG.cfg: a PAF file that describes the XXXX configuration set (see [22], chapter 3 for details). This file contains the dictionary names associated to the xxmcfgINS.cfg file (normally: "ICB_CFG OSB STOO_CFG") and a reference to the xxmcfgINS.cfg file itself. Once created, this file is normally not modified.
· xxmcfgSTART.cfg: a PAF file that contains information related to the Instrument Software start-up, such as the simulation level (keyword INS.CON.OPMODE).
· <motor>.dbcfg: Each instrument motor has an associated <motor>.dbcfg file, that contains the corresponding MCM configuration of the motor. These files are created and maintained with the motor engineering interface (motei). See [15] for details.
8.3 FROM THE CONFIGURATION FILES TO THE RUNNING SYSTEM
When the instrumentation software is installed, the configuration files are placed in the directory: $INS_ROOT/SYSTEM/COMMON/CONFIGFILES.
In addition, based on their contents, the utility icbConfigSet creates one OLDB backup file for each ICS LCU. These OLDB backup files are placed in: $VLTDATA/config/<LCU>.dbcfg.
When the ICS WS processes are started, they configure themselves extracting the needed information directly from the configuration files stored in the INS_ROOT.
The ICS LCUs configure themselves when they boot: the LCU OLDB is initialized during booting with the corresponding <LCU>.dbcfg file. This allows the ICS LCU processes to read the configuration from the LCU OLDB.
Note that configuration changes applied directly to the running ICS are always transient. When the ICS WS processes are restarted or when the ICS LCUs are rebooted, they always initialize themselves with the configuration stored in INS_ROOT. To make a permanent configuration change, the configuration files themselves have to be updated.
8.4 DESIGN CONFIG. PARAMETERS VS. NORMAL CONFIG. PARAMETERS
The configuration files store two types of parameters:
8.4.1 Design Config. Parameters
The design config. parameters have values that are not only stored in the configuration files themselves, but they are also stored (or hardcoded) in the ICS OLDB structure or in the instrument specific part of the ICS software. These parameters are set when the instrumentation software is designed, and can not be modified later on without also modifying and reinstalling the control system. I.e., in practice, the design config. parameters are not allowed to be modified once the control system is in operation.
Example: The acronym of the ICS software devices.
Each software device has an associated OLDB point. The alias name of this point has to be the acronym of the software device (in uppercase). E.g. the software device `tal' (the ThAr lamp) has an associated OLDB point with alias `TAL'. As the software device acronym is `hardcoded' into the OLDB, it is not allowed to modify this config. parameter. If it is modified, then the OLDB has to be rebuilt.
8.4.2 Normal Config. Parameters
The values of normal config. parameters can be updated at any time. ICS reads the updated values when the ICS WS processes are started, resp. when the ICS LCUs are rebooted. Some normal config. parameters are marked as Calibration Config. Parameters, when they are expected to be updated during calibrations.
8.5 UPDATING AND TESTING THE ICS CONFIGURATION
8.5.1 Updating Design Config. Parameters
If you are implementing an instrument specific ICS based on icb, and you need to update design config. parameters (see section 8.4.1 above), then please refer to the tutorial, section 5.5. Basically, the update has to be done as follows:
2. Update the source files (probably a dbl file in module xxi) according to the modified config. parameters.
Only the responsible software developer is allowed to update design config. parameters!
8.5.2 Hardware control
For every ICS software device accessing some piece of hardware through LCU interface boards, it is strongly recommended, before trying to control the hw from ICS for the very first time, to use standard VLT tools to test at a lower level (LCU) if the hw is properly configured. These tools are:
2. Inducer (see inducerStarter) for devices controlled through standard digital or analog I/O boards, such as lamps or shutters.
8.5.3 Updating Normal Config. Parameters
Assuming that ICS is installed and running, the procedure to update normal config. parameters and test the ICS configuration is as follows:
1. To test software devices that use standard digital or analog I/O boards, such as lamps or shutters, use the inducer tool:
5. If you only modified config. parameters of an existing ICS software device(s), then it is sufficient to place the device(s) in state OFF and back ONLINE. The ICS software device(s) re-load the configuration during the Loaded to Stand-by state transition:
9. Save the new configuration in the xxmcfg module (replace `xx' with the prefix of your instrument!):
The cycle 1.-6. is slow, because the LCU in some cases needs to be rebooted. This is an additional reason to use first as far as possible standard VLT tools to find and test the right configuration (see section 8.5.2). The standard VLT tools allow to update and test the configuration on the fly, without rebooting the LCU.
8.6 CONFIGURATION PARAMETERS
The configuration files contain FITS keywords that describe the instrument. All standard configuration FITS keywords are listed in the dictionary ESO-VLT-DIC.ICB_CFG. Additional, instrument specific keywords that an instrument may need are described in the instrument specific Software User Manual.
The standard configuration FITS keywords are grouped as follows:
The next sections describe these groups in detail.
Unless otherwise specified, the configuration file where the described keywords are supposed to be present is xxmcfgINS.cfg.
8.7 GENERAL INSTRUMENT CONFIGURATION
8.7.1 Instrument Identifier
The instrument identifier (e.g. `UVES', represented with `XXXX' in this document) is widely used in the instrumentation software to identify files, processes and data items. In the ICS OLDB, the instrument identifier is used as the alias for the instrument OLDB point :Appl_data:XXXX.
8.7.2 Software Module Prefix
The software module prefix are the two first letters of the instrumentation software modules (e.g. `uv', represented with `xx' in this document, see section 2.2). This value should be defined in agreement with ESO (vltsccm@eso.org), as the corresponding software modules names, derived from the prefix, must be available in the Software Archive. The software module prefix is usually selected to be the same as the network subnet name assigned to the instrument, as listed in [12], section 5.1. For obvious reasons, once selected, the software module prefix can not be modified.
8.7.3 Instrument OLDB Root Point
Normally the instrument OLDB root point is located in ":Appl_data:XXXX". If the OLDB has to be placed in a different location (under point :Appl_data), then this can be specified with the INS.CON.DBROOT keyword. The ICS OLDB branch is always placed below the instrument OLDB root point with name "ICS", by default: ":Appl_data:XXXX:ICS".
8.8 WORKSTATION AND LCU ENVIRONMENTS
8.8.1 Instrument Workstation Environment
The instrument workstation environment should have the same name as the instrument workstation itself. The name of the instrument workstations are listed in [12], section 5.3.
8.8.2 Instrument LCU Environments
The LCU environments have the same name as the target LCUs. The LCU names can be found in [12], section 5.3. Only the instrument LCUs assigned to ICS that control instrument functions should be registered with INS.CON.LCUENVi.
E.g. UVES has six LCUs: two LCUs that control the instrument functions, two slit-viewer LCUs and two FIERA LCUs. Only the first two are registered here:
8.9 ICS GENERAL CONFIGURATION
Normally, only the basic configuration keywords need to be specified in the instrument configuration. The optional keywords have meaningful defaults and are usually not needed. They are described in section 8.14.
ICS Basic Configuration Keywords Sec. Keyword Type Description INS.CON.OPMODE Normal Simulation mode (NORMAL or LCU_SIM) INS.CON.ONLINE Normal If T, sensors are placed online when the LCU boots.8.9.1 Simulation Mode
The initial simulation mode is set with the INS.CON.OPMODE keyword (see section 4.2).
· LCU_SIM: LCU simulation, commands are simulated in the instrument workstation. Select this option, if you do not have any instrument LCU.
· HW_SIM: Hw simulation, send commands to the ICS LCUs, where the control over some parts of the hardware is disabled. The missing parts of the hardware are simulated at LCU level.
This keyword should normally be present only in the file xxmcfgSTART.cfg (not in xxmcfgINS.cfg).
8.9.2 Place Sensors Online When The LCU Boots
This keyword specifies if sensors should be placed in the state ONLINE and start monitoring immediately after the ICS LCUs have booted, without receiving any command from the workstation.
When creating ICS from scratch, it is better to leave this flag `F', because initially the sensor hardware is not available.
For normal operations, the keyword should be set to `T', to make sure that sensors are always recording data, even before the LCUs receive the first commands from the workstation.
8.10 ICS SOFTWARE DEVICES
ICS Software Device List Keywords Sec. Keyword Type Description INS.CON.DEVNUM Design Number of ICS software devices. INS.CON.DEVICEi Design Device FITS prefix used in the configuration file.8.10.1 List of ICS Software Devices
To retrieve the specific ICS software device configuration, the configuration file needs a list of the FITS prefix used to register the software device configuration data. This config. FITS prefix has to be selected according to the ICS software device type, as listed in the tables below.
ICS Software Device Types: Lamps and Shutters Name Description Hardware Configuration FITS Prefix icbLAMP Calibration lamp Digital board INS.LAMPi icbSHUTTER Shutter Digital board INS.SHUTiExample: The ICS software device list for an instrument that has two filter wheels, digital sensors and an ESO cabinet cooling controller looks as follows:
8.10.2 Notes Regarding the Description of Individual ICS Software Devices
· The next sections of this manual describe the individual ICS software devices. These sections describe not only the config. FITS keywords, but also the FITS keywords accepted by the SETUP and STATUS commands. These tables are included only for reference.
· When ICS is created for the first time from scratch, then only the design config. keywords need to be defined, all other config. keywords can be skipped the first time the ICS software is built. Specifying only the design FITS keywords is sufficient to execute ICS in simulation (with several restrictions: e.g. a filter wheel can only be moved with the INS.FILTi.NO keyword, as the filter element names are not known yet).
Once the ICS LCUs have booted correctly and the ICS WS processes are running for the first time, the rest of the specific ICS software device config. keywords can be defined.
· If ICS is already operational, then design config. FITS keywords can not be modified (see section 8.4.1).
· The first column of the config. FITS keywords table specifies the manual section where the config. parameters are described. This is usually located below the config. keywords table, except for some common keywords that are described once in separate sections.
8.10.3 Common Config. Keywords
The ICS software devices have the following common config. keywords:
8.10.3.1 Acronym of the ICS software device
The acronym (e.g. `TAL') is used to identify the ICS software device. It may be used in the SETUP and STATUS commands. The alias of the device OLDB point is equal to the device acronym in uppercase. This allows to access e.g. the state of the device as follows: <alias>TAL.state.
8.10.3.2 Description of the ICS software device
The description is only displayed in the ICS panels, it is not used by the ICS control software itself.
8.10.3.3 LCU managing the device
The LCU number is the INS.CON.LCUENVi index of the LCU that manages the device.
8.11 LAMPS AND SHUTTERS
8.11.1 Lamp (icbLAMP)
The icbLAMP ICS software device allows to control a lamp accessed via a VLT standard digital I/O board. The device can switch the lamp on/off with the SETUP command, or between STANDBY and ONLINE state transitions. Support for warm-up times is supplied.
The SETUP command accepts the following FITS keywords:
Lamp SETUP Keywords Keyword Description INS.LAMPi.ST Turn the lamp on (T) or off (F). INS.LAMPi.WAIT Max. time to wait for lamp warm-up (see 8.11.1.2).The STATUS reports the following FITS keywords:
Lamp STATUS Keywords Keyword Description INS.LAMPi.ST Lamp is on (T) or off (F). INS.LAMPi.ID Hardware identification of the lamp. INS.LAMPi.NAME ESO name of the lamp.The configuration keywords are the following:
8.11.1.1 Hardware identification and ESO name
These two values are reported by the STATUS and placed in the header.
8.11.1.2 Warm-up time and max. time to wait for the lamp warm-up
If the lamp is immediately ready to be used after turning it on, then these keywords can be skipped.
The INS.LAMPi.WARMUP keyword registers the time that the lamp needs to warm-up before it can be used. The INS.LAMPi.WAIT keyword registers the max. time that the SETUP command will wait for the lamp to complete it's warm-up period.
If the warm-up time is short, then both keywords can be set to the same value.
If the warm-up time is very long, thenINS.LAMPi.WAIT should be set to a lower reasonable value, to avoid that a BOB sequence is blocked for a long time. If the SETUP command realizes that the remaining warm-up time is greater than the time it is allowed to wait, then it will immediately return an error.
Examples for a lamp with a long warm-up time:
The command will wait the default WAIT time and return without error if the lamp is ready, otherwise it will return an error (assuming that the default WAIT is not 0).
8.11.1.3 Lamp can be changed
The INS.LAMPi.CHGABLE keyword can be normally skipped, unless the lamp can be changed by operations according to user requirements (in this case, it should be set to `T').
8.11.1.4 Digital signals configuration
The INS.LAMPi.SIG* keywords are used to specify how the lamp is connected to the VLT standard digital I/O board. It is recommended to connect normal lamps as follows to the digital I/O board:
· The INS.LAMPi.TIMEOUT keyword specifies the time [msec] that the feedback signal needs to report the change of lamp state. The default is 2000 msecs.
8.11.2 Shutter (icbSHUTTER)
The icbSHUTTER ICS software device allows to control a shutter accessed via a VLT standard digital I/O board.
The SETUP command accepts the following FITS keywords:
Shutter SETUP Keywords Keyword Description INS.SHUTi.ST Open (T) and close (F) the shutter.The STATUS reports the following FITS keywords:
Shutter STATUS Keywords Keyword Description INS.SHUTi.ST Shutter is open (T) or closed (F). INS.SHUTi.ID Hardware identification of the shutter. INS.SHUTi.NAME ESO name of the shutter.The configuration keywords are the following:
8.11.2.1 Hardware identification and ESO name
These two values are reported by the STATUS and placed in the header.
8.11.2.2 Digital signals configuration
The INS.SHUTi.SIG* keywords are used to specify how the shutter is connected to the VLT standard digital I/O board. It is recommended to connect shutters as follows to the digital I/O board:
· The INS.SHUTi.TIMEOUT keyword specifies the time [msec] that the feedback signal needs to report the change of shutter state. The default is 5000 msecs.
8.12 MOTORIZED FUNCTIONS
All ICS software devices that access motors do so through the Motor Control Module (MCM), therefore the motors are controlled via the hardware supported by MCM (see [14]). Apart from configuring the parameters listed below, it is necessary to configure the motor parameters in the MCM OLDB of each device. This is done with motei as described in section 8.5.3, point 2.
Motorized ICS software devices accept the following FITS keywords for maintenance purposes1:
Notes related with MCM updates with motei:
1. Important: If a motor moves to named positions (e.g. any element wheel, a filter wheel), then the names in the MCM named positions table must be the index of the position. The first entry (index = 0) is not used. I.e. the named positions names must be: "DUMMY", "1", "2", "3", "4", ...
2. Most motors with dynamic ranges have to register a user unit conversion function in the MCM unit conversion table, otherwise unit conversions will not work. The unit conversion function is registered in the sample motor configurations supplied with the XXXX Template Instrument.
8.12.1 ADC (icbMOT_ADC)
The icbMOT_ADC ICS software device is used to drive ADCs functions. It compensates for the atmospheric dispersion according to the current telescope position, temperature and pressure (AUTO mode). Two ADC functions have to be used.
The SETUP command accepts the following FITS keywords:
ADC SETUP Keywords Keyword Description INS.ADCi.MODE OFF: Leave the motor standing.AUTO: compensate atmospheric dispersion.The STATUS reports the following FITS keywords:
ADC STATUS Keywords Keyword Description INS.ADCi.MODE Current mode. INS.ADCi.POSANG Current motor position [deg].The configuration keywords are the following:
8.12.1.1 Mode OFF
In mode OFF, the motor is standing. It is assumed, that the ADC is positioned outside the light path when it is in this mode.
8.12.1.2 Mode AUTO
In mode AUTO, the motor tracks according to the telescope position received. The motor position is recalculated each INS.ADCi.PERIOD msecs. according to the following formulas:
8.12.1.3 RA, Dec, temperature and pressure
The ADC device needs to receive regular updates of the RA, Dec, temperature and pressure. These values are stored in the device OLDB point (e.g. <alias>ADC1.ra).
It is recommended, that the ICS WS process regularly reads this information (RA and Dec from the local TCS status branch) and if the LCU is available, regularly updates the corresponding OLDB attributes in the LCU. This makes sure, that e.g. RA, Dec coordinates used by the ADC are really the ones the telescope is pointing to, regardless if the telescope is moved from a template or by the telescope operator.
8.12.2 Depolarizer (icbMOT_DPOR)
The icbMOT_DPOR ICS software device rotates the motor with a constant speed (the MCM default speed) or leaves it standing.
The SETUP command accepts the following FITS keywords:
Depolarizer SETUP Keywords Keyword Description INS.DPOR.ST Rotate with constant speed (T) or leave the function standing (F).The STATUS reports the following FITS keywords:
Depolarizer STATUS Keywords Keyword Description INS.DPOR.ST Motor is rotating (T) or is standing (F). INS.DPOR.POS Current motor position [deg].The configuration keywords are the following:
8.12.3 Derotator (icbMOT_DROT)
The icbMOT_DROT ICS software device can be used when an instrument is mounted directly on top of the Nasmyth platform. When the device receives the current telescope position, it moves the derotator to compensate for the field rotation, either in SKY or ELEVation mode.
The SETUP command accepts the following FITS keywords:
Derotator SETUP Keywords Keyword Description INS.DROT.MODE STAT: Leave the motor standing in the POSANG position.SKY: derotate in sky mode.ELEV: derotate in elevation mode. INS.DROT.RA Telescope position [hhmmss.mm] and [ddmmss.mm] (see 8.12.3.3). INS.DROT.DEC INS.DROT.POSANG Start position angle [deg]. INS.DROT.STATINDX STAT position index (see INS.DROT.STATENCi below).The STATUS reports the following FITS keywords:
Derotator STATUS Keywords Keyword Description INS.DROT.MODE Current mode. INS.DROT.POSANG Current motor position [deg].The configuration keywords are the following:
8.12.3.1 Mode STAT
In mode STAT, the motor is positioned according to the following formula:
· The INS.DROT.STATENC is the zero position in encoder units. The INS.DROT.STATENCi vector can be used, when the derotator has to be placed in different static positions, according to the position of other instrument functions. In this case, the ICS WS server should send the right INS.DROT.STATINDX value to the derotator.
· The motor is not moved, if the function is already positioned within INS.DROT.TOLERANC degrees from the requested position (e.g. if the current position is 10.019 deg, the requested position is 10.00 deg and the tolerance is 0.02 deg, then the motor is not moved).
8.12.3.2 Mode SKY and ELEV
In mode SKY and ELEV, the motor tracks according to the telescope position received. The motor position is recalculated each INS.DROT.PERIOD msecs. according to the following formulas:
If the necessary speed to reach the new position is within the specified limits (INS.DROT.SPDMIN and INS.DROT.SPDMAX), then the motor is moved by speed, otherwise the motor is moved in position mode.
8.12.3.3 RA, Dec
This device needs regular updates of RA, Dec. These values are stored in the device OLDB point (e.g. <alias>DROT.ra). See 8.12.1.3 for the recommended way of supplying these values.
8.12.4 Filter Wheel (icbMOT_FILTER)
The icbMOT_FILTER ICS software device controls a filter wheel. The element position is usually selected with the element name.
The SETUP and STATUS commands accept the following FITS keywords:
Filter Wheel SETUP and STATUS Keywords Keyword Description INS.FILTi.NO Position index (1..n) INS.FILTi.ID Filter unique identifier. INS.FILTi.NAME Filter name.The configuration keywords are the following:
8.12.4.1 Filter elements can be changed
The INS.FILTi.CHGABLE keyword can be normally skipped, unless the filter elements can be changed by operations according to user requirements (in this case, it should be set to `T').
8.12.4.2 List of mounted filter elements
INS.FILTi.POSNUM is the number of wheel positions, while keyword INS.FILTj.POSIDi contains the filter unique identifier of the filter element mounted in position i. The identifier is used to retrieve the rest of the filter data from the filter elements table.
8.12.4.3 Filter elements table
The INS.FILTi.IDi, INS.FILTi.NAMEi and INS.FILTi.FOCUSi keywords form a table that registers the characteristics of the available filters. The last index (IDi, NAMEi, FOCUSi) is used to identify the table row assigned to one filter element, this index is not related with the index where the filter element is eventually mounted (POSIDi).
The INS.FILTi.FOCUSi keyword is only needed, if a focus offset [Enc] related to the filter element is needed to focus the instrument (e.g. EMMI instrument).
Note that filter F3 is mounted in position 2, but is the 3. filter element registered in the filter element table. Filter F2 described in the table is not mounted.
8.12.5 Grating Wheel (icbMOT_GRATING2)
The icbMOT_GRATING2 ICS software device controls a wheel that has usually two gratings mounted back to back. The position is selected specifying the grating name and central wavelength. For accuracy, the positioning is done with a two step absolute motion (see [14], section 2.4.5).
The SETUP and STATUS commands accept the following FITS keywords:
The configuration keywords are the following:
8.12.5.1 Elements can be changed
The INS.GRATi.CHGABLE keyword can be normally skipped, unless the elements can be changed by operations according to user requirements (in this case, it should be set to `T').
8.12.5.2 List of mounted elements
INS.GRATi.POSNUM is the number of wheel positions, while keyword INS.GRATj.POSIDi contains the unique identifier of the element mounted in position i. The identifier is used to retrieve the rest of the element data from the elements table.
8.12.5.3 Elements table
The INS.GRATi.*i keywords listed above form a table that registers the characteristics of the available elements. The last index (e.g. IDi, NAMEi) is used to identify the table row assigned to one element, this index is not related with the index where the element is eventually mounted (POSIDi).
· The INS.GRATi.WLENMINi and INS.GRATi.WLENMAXi keywords specify the range for the INS.GRATi.WLEN keyword.
· The INS.GRATi.ZORDERi, INS.GRATi.GROOVESi and INS.GRATi.TEMPRAMPi keywords are needed to calculate the wheel position (see below).
· The INS.GRATi.FOCUSi keyword is only needed, if a focus offset [Enc] related to the element is needed to focus the instrument (e.g. EMMI instrument).
· The INS.GRATi.ALIGNi keyword is only needed, if the gratings can be changed by operations and the wheel position needs to be realigned (see section 8.12.5.5).
8.12.5.4 Grating wavelength to position conversion
The grating wheel is positioned according to the following formulas (see note in section 8.12):
· The motor is not moved, if the function is already positioned within INS.GRATi.TOLERANC nm from the requested position (e.g. if the current position is 500.05 nm, the requested position is 500.00 nm and the tolerance is 0.1 nm, then the motor is not moved).
Caution: The named position reported by MCM is used to identify the currently selected grating. Therefore, the positions registered in the MCM OLDB named positions table have to cover the COMPLETE range [Enc] where the grating may be positioned according to the WLEN range [nm]. If this is not the case, then MCM will not always report the correct grating, and the software device will not work correctly.
8.12.5.5 Alignment
If the gratings can be changed by operations, then the wheel position has probably to be realigned. The alignment procedure can register the needed wheel position offset in the INS.GRATi.ALIGN keyword without touching the rest of the configuration.
The INS.GRATi.ALIGNMIN and INS.GRATi.ALIGNMAX keywords specify the min. and max. value that can be assigned to the alignment value.
8.12.6 Mirror Wheel (icbMOT_MIRROR)
The icbMOT_MIRROR ICS software device controls a mirror wheel. The element position is usually selected with the element name.
The SETUP and STATUS commands accept the following FITS keywords:
Mirror Wheel SETUP and STATUS Keywords Keyword Description INS.MIRRi.NO Position index (1..n) INS.MIRRi.ID Element unique identifier. INS.MIRRi.NAME Element name.The configuration keywords are the following:
8.12.6.1 List of mounted elements
INS.MIRRi.POSNUM is the number of wheel positions, while keyword INS.MIRRj.POSIDi contains the unique identifier of the element mounted in position i. The identifier is used to retrieve the rest of the data from the elements table described below.
8.12.6.2 Elements table
The INS.MIRRi.IDi and INS.MIRRi.NAMEi keywords form a table that registers the names of the available elements. The last index (IDi, NAMEi) is used to identify the table row assigned to one element, this index is not related with the index where the element is eventually mounted (POSIDi).
8.12.7 Optical Function with Discrete Positions (icbMOT_OPTI)
The icbMOT_OPTI ICS software device controls any motorized function where predefined elements have to be selected. The element is usually selected with it's name.
The SETUP and STATUS commands accept the following FITS keywords:
The configuration keywords are the following:
8.12.7.1 Device FITS prefix
The device FITS prefix specifies the system and category of the FITS keywords recognized by the SETUP and STATUS commands. The prefix is shown here as "<prefix>".
then the SETUP and STATUS commands will recognize the keywords:
Note that all config. keywords start with INS.OPTIi, regardless of the INS.OPTIi.PREFIX value.
8.12.7.2 Elements can be changed
The INS.OPTIi.CHGABLE keyword can be normally skipped, unless the elements can be changed by operations according to user requirements (in this case, it should be set to `T').
8.12.7.3 List of mounted elements
INS.OPTIi.POSNUM is the number of available positions, while keyword INS.OPTIj.POSIDi contains the unique identifier of the element mounted in position i. The identifier is used to retrieve the rest of the data from the elements table.
8.12.7.4 Elements table
The INS.OPTIi.*i keywords listed above form a table that registers the characteristics of the available elements. The last index (e.g. IDi, NAMEi) is used to identify the table row assigned to one element, this index is not related with the index where the element is eventually mounted (POSIDi).
· The INS.OPTIi.FOCUSi keyword is only needed, if a focus offset [Enc] related to the element is needed to focus the instrument (e.g. EMMI instrument).
· The INS.OPTIi.ALIGNi keyword is only needed, if the elements can be changed by operations and the element position needs to be realigned.
8.12.8 Optical Function with Continuous Positions (icbMOT_POS)
The icbMOT_POS ICS software device controls any motorized function that is set with a numeric value, within a continuous range. For accuracy, the positioning is done with a two step absolute motion (see [14], section 2.4.5).
The SETUP and STATUS commands accept the following FITS keywords:
Optical Function SETUP and STATUS Keywords Keyword Description <prefix>.POS Position in user units.The configuration keywords are the following:
8.12.8.1 Device FITS prefix
The device FITS prefix specifies the system and category of the FITS keywords recognized by the SETUP and STATUS commands. The prefix is shown here as "<prefix>".
then the SETUP and STATUS commands will recognize the keyword:
Note that all config. keywords start with INS.POSi, regardless of the INS.POSi.PREFIX value.
8.12.8.2 User units to encoder position conversion
The motor is positioned according to the following formula (see note in section 8.12):
· Keyword INS.POSi.UNIT is the name of the user units, e.g.: "mm". This user unit must be registered in the user unit conversion table of MCM, otherwise the device will not work.
· The motor is not moved, if the function is already positioned within INS.POSi.TOLERANC user units from the requested position (e.g. if the current position is 5.09 mm, the requested position is 5.0 mm and the tolerance is 0.1 mm, then the motor is not moved).
8.12.9 Length Slit or Dekker (icbMOT_SLIT2_LEN)
The icbMOT_SLIT2_LEN ICS software device controls a slit function (or dekker), that has two motors (jaws): one on each side of the slit. Both motors are moved simultaneously to set the slit length. The positioning is done with a two step absolute motion (see [14], section 2.4.5).
The icbMOT_SLIT2_WID ICS software device is identical to the icbMOT_SLIT2_LEN device, except that it uses different FITS keywords (e.g. INS.SLITi.WID instead of INS.SLITi.LEN).
If both instrument functions exist, then the following keywords are recommended to be used:
With the above keywords, the SETUP command will recognize the keywords INS.SLITi.LEN and INS.SLITi.WID. Each one will be sent to the correct ICS software device.
The SETUP and STATUS commands accept the following FITS keywords:
Length Slit SETUP and STATUS Keywords Keyword Description INS.SLITi.LEN Slit position [arcsec].The configuration keywords are the following:
Length Slit Config. Keywords Sec. Keyword Type Description INS.SLITi.DEVNAME Design Acronym of the ICS software device. INS.SLITi.DEVDESC Normal Description of the ICS software device. INS.SLITi.LCUID Design LCU number of the LCU managing the device (1..n). INS.SLITi.SWSIM Normal Device simulation flag (T/F). INS.SLITi.DEVTYPE Design Device type (value="LEN2") 8.12.9 top INS.SLITi.PREFIX Design Prefix for SETUP and STATUS FITS keywords. INS.SLITi.LENMIN Normal Min. slit length [arcsec]. INS.SLITi.LENMAX Normal Max. slit length [arcsec]. INS.SLITi.TOLERANC Normal Slit length tolerance [arcsec]. INS.SLITi.X1OFFSET Normal Motor 1 reference position [Enc]. INS.SLITi.X2OFFSET Normal Motor 2 reference position [Enc]. INS.SLITi.X1RESOL Normal Motor 1 encoder resolution [Enc/deg]. INS.SLITi.X2RESOL Normal Motor 2 encoder resolution [Enc/deg]. INS.SLITi.X1LENMIN Normal Motor 1 min.position [arcsec]. INS.SLITi.X1LENMAX Normal Motor 1 max. position [arcsec]. INS.SLITi.X2LENMIN Normal Motor 2 min. position [arcsec]. INS.SLITi.X2LENMAX Normal Motor 2 max. position [arcsec].8.12.9.1 Device type
To differentiate the slit wheel from the other slits, the INS.SLITi.DEVTYPE keyword must have the value "LEN2".
8.12.9.2 Slit length range and tolerance
· The motor is not moved, if the function is already positioned within INS.SLITi.TOLERANC arcsec from the requested position (e.g. if the current position is 5.09 arcsec, the requested position is 5.0 arcsec and the tolerance is 0.1 arcsec, then the motor is not moved).
8.12.9.3 Length to encoder position conversion
The motors are positioned according to the following formulas (see note in section 8.12):
· Keywords INS.SLITi.X1RESOL and INS.SLITi.X2RESOL must match the resolution of the used encoders (as registered in the MCM OLDBs).
8.12.9.4 Motor maintenance SETUP keywords:
As this ICS software device controls two motors, the maintenance SETUP keywords have to differentiate between both motors. The keywords are the following (see section 8.12 for details):
8.12.10 Width Slit (icbMOT_SLIT2_WID)
The icbMOT_SLIT2_WID ICS software device controls a slit function, that has two motors (jaws): one on each side of the slit. Both motors are moved simultaneously to set the slit width. The positioning is done with a two step absolute motion (see [14], section 2.4.5).
The icbMOT_SLIT2_LEN ICS software device is identical to the icbMOT_SLIT2_WID device, except that it uses different FITS keywords (e.g. INS.SLITi.LEN instead of INS.SLITi.WID).
If both instrument functions exist, then follow the instructions given in section 8.12.9.
The SETUP and STATUS commands accept the following FITS keywords:
Width Slit SETUP and STATUS Keywords Keyword Description INS.SLITi.WID Slit position [arcsec].The configuration keywords are the following:
Width Slit Config. Keywords Sec. Keyword Type Description INS.SLITi.DEVNAME Design Acronym of the ICS software device. INS.SLITi.DEVDESC Normal Description of the ICS software device. INS.SLITi.LCUID Design LCU number of the LCU managing the device (1..n). INS.SLITi.SWSIM Normal Device simulation flag (T/F). INS.SLITi.DEVTYPE Design Device type (value="WID2") 8.12.9 top INS.SLITi.PREFIX Design Prefix for SETUP and STATUS FITS keywords. INS.SLITi.WIDMIN Normal Min slit width [arcsec]. INS.SLITi.WIDMAX Normal Max. slit width [arcsec]. INS.SLITi.TOLERANC Normal Width tolerance [arcsec]. INS.SLITi.Y1OFFSET Normal Motor 1 reference position [Enc]. INS.SLITi.Y2OFFSET Normal Motor 2 reference position [Enc]. INS.SLITi.Y1RESOL Normal Motor 1 encoder resolution [Enc/deg]. INS.SLITi.Y2RESOL Normal Motor 2 encoder resolution [Enc/deg]. INS.SLITi.Y1WIDMIN Normal Motor 1 min.position [arcsec]. INS.SLITi.Y1WIDMAX Normal Motor 1 max. position [arcsec]. INS.SLITi.Y2WIDMIN Normal Motor 2 min. position [arcsec]. INS.SLITi.Y2WIDMAX Normal Motor 2 max. position [arcsec].8.12.10.1 Device type
To differentiate the slit wheel from the other slits, the INS.SLITi.DEVTYPE keyword must have the value "WID2".
8.12.10.2 Slit width range and tolerance
· The motor is not moved, if the function is already positioned within INS.SLITi.TOLERANC arcsec from the requested position (e.g. if the current position is 5.09 arcsec, the requested position is 5.0 arcsec and the tolerance is 0.1 arcsec, then the motor is not moved).
8.12.10.3 Width to encoder position conversion
The motors are positioned according to the following formulas (see note in section 8.12):
· Keywords INS.SLITi.Y1RESOL and INS.SLITi.Y2RESOL must match the resolution of the used encoders (as registered in the MCM OLDBs).
8.12.10.4 Motor maintenance SETUP keywords:
As this ICS software device controls two motors, the maintenance SETUP keywords have to differentiate between both motors. The keywords are the following (see section 8.12 for details):
8.12.11 Slit Wheel (icb_MOT_SLITS)
The icbMOT_SLITS ICS software device controls a slit wheel. The slit is usually selected with it's name.
The SETUP and STATUS commands accept the following FITS keywords:
The configuration keywords are the following:
8.12.11.1 Device type
To differentiate the slit wheel from the other slits, the INS.SLITi.DEVTYPE keyword must have the value "WHEEL".
8.12.11.2 Elements can be changed
The INS.SLITi.CHGABLE keyword can be normally skipped, unless the elements can be changed by operations according to user requirements (in this case, it should be set to `T').
8.12.11.3 List of mounted elements
INS.SLITi.POSNUM is the number of available positions, while keyword INS.SLITj.POSIDi contains the unique identifier of the element mounted in position i. The identifier is used to retrieve the rest of the data from the elements table.
8.12.11.4 Elements table
The INS.SLITi.*i keywords listed above form a table that registers the characteristics of the available slits. The last index (e.g. IDi, NAMEi) is used to identify the table row assigned to one element, this index is not related with the index where the element is eventually mounted (POSIDi).
8.12.12 Camera Tilt (icbMOT_TILT)
The icbMOT_TILT ICS software device controls a camera tilt function.
For accuracy, the positioning is done with a two step absolute motion (see [14], section 2.4.5).
The SETUP and STATUS commands accept the following FITS keywords:
Camera Tilt SETUP and STATUS Keywords Keyword Description INS.TILTi.POS Tilt position [pix].The configuration keywords are the following:
8.12.12.1 Pixel to encoder position conversion
The motor is positioned according to the following formula (see note in section 8.12):
· The motor is not moved, if the function is already positioned within INS.TILTi.TOLERANC pixels from the requested position (e.g. if the current position is 5.09 pix, the requested position is 5.0 pix and the tolerance is 0.1 pix, then the motor is not moved).
8.13 SENSORS
This section describes all sensor ICS software devices supported by Base ICS. Below features common to all sensor devices are described; the next subsections describe each sensor device type in detail.
8.13.1 Common Sensor Software Device Config. Keywords
8.13.1.1 Device type
The config. keywords INS.SENSORi.* describe all types of sensors. Therefore, it is necessary to register the type of the sensor software device in the INS.SENSORi.DEVTYPE keyword. This identifies the type of hardware that the sensor software device should access.
8.13.1.2 Device hardware port
The sensor values managed by one sensor device are usually connected to a single hardware port (INS.SENSORi.PORT). The hardware port of analog sensors is normally a serial port (e.g. "/iser0" or "/tyCo/1"), the hardware `port' of a digital sensor device is a VLT standard digital I/O board (e.g. "/acro0").
8.13.1.3 The sensor values table
Each sensor software device manages a set of sensor values, that are registered in a sensors values table (INS.SENSORi.*i).
The table registers at least the following items:
· INS.SENSORi.NUM: Size of the table, i.e. number of sensor values managed by the sensor software device.
· INS.SENSORi.NAMEi: The sensor value name is an acronym. Usually the acronym specified in the electr. design document is used (if available).
· INS.SENSORi.DESCi: This sensor value description is not used by the control software itself. It may be used in the ICS panels.
· INS.SENSORi.HEADERi: This flag (T/F) specifies, if the sensor value should be reported in the image FITS header or not (i.e. if it should be returned with the STATUS -header command).
· INS.SENSORi.FITSi: Each sensor value must be assigned a FITS keyword. Usually keywords INS.SENSi.* and INS.TEMPi.VAL are used. The index SENSi (and TEMPi) of each sensor value must be unique within the instrument. The last part of the INS.SENSi.* keyword should be selected according to the value type of the sensor:
There is no relation between sensor device indexes (SENSORi) and sensor value indexes (SENSi), e.g. one sensor device INS.SENSOR3 can manage the sensor values INS.SENS12 to INS.SENS16.
The following FITS keywords may be used by several sensor value tables (see the individual sensor software device descriptions):
Hardware address and/or id. number to identify the specific sensor value to be reported. The exact meaning of the hardware address depends of the software device type (INS.SENSORi.DEVTYPE).
8.13.1.4 Sensor values
Sensor values are retrieved with the STATUS command or from the software device OLDB point, from vector status (and vector last, if available).
8.13.1.5 SETUP command
Sensor software devices do not accept the SETUP command, unless noted otherwise in the specific sensor device description.
8.13.2 ADAM Analog Sensors (icbSEN_ADAM)
This ICS software device allows to access up to 16 ADAM devices connected to a single serial port. Each ADAM device must have a unique address `x' (see below). Each ADAM device can report up to 8 different analog values `y' (0-7).
8.13.2.1 Sensor value hardware address
The hardware address must have the format `xy', where `x' identifies the ADAM device, and `y' the value within the selected ADAM device, e.g. address 34 means to access the 4. value of the 3. ADAM device.
The retrieval of values is more efficient, if all values of the same ADAM device `x' are placed one below the other in the sensor values table.
8.13.2.2 Sensor value report type
INS.SENSORi.SENTYPEi accepts the following types:
"ANALOG", "PRESSURE", "TRUE_FALSE", "ON_OFF", "OPEN_CLOSED", "OPEN_CLOSED2".
All the types are described in section 8.13.1.3, except OPEN_CLOSED2, that is described below.
The "OPEN_CLOSED2" report type is used when there are two different signals to report the OPEN and CLOSED conditions. This report type assumes:
· If any of the threshold values described above is negative, then the resulting boolean flag is reversed.
· If both signals are active, then the status vector in the software device OLDB point reports the status: "FAULT".
8.13.2.3 Serial port
The serial port to access the ADAM devices is preconfigured as follows:
Baudrate = 9600, CharBits = 8, StopBits = 1, Parity = 0 (none).
8.13.3 Barometer Sensor (icbSEN_BAROMETER)
This ICS software device allows to access a VAISALA barometer sensor connected to a serial port..
Barometer Sensor Config. Keywords Sec. Keyword Type Description INS.SENSORi.DEVNAME Design Acronym of the ICS software device. INS.SENSORi.DEVDESC Normal Description of the ICS software device. INS.SENSORi.LCUID Design LCU number of the LCU managing the device (1..n). INS.SENSORi.SWSIM Normal Device simulation flag (T/F). INS.SENSORi.DEVTYPE Design Device type (value="BAROMETER"). INS.SENSORi.PORT Normal Hardware device (e.g. "/iser0"). 8.13.1.3 and INS.SENSORi.NUM Normal Number of managed sensor values. INS.SENSORi.NAMEi Normal Sensor value name (use value="BARO"). INS.SENSORi.DESCi Normal Sensor value description. INS.SENSORi.HEADERi Normal If T, report sensor value in the image FITS header. INS.SENSORi.FITSi Normal Sensor value FITS keyword. INS.SENSORi.SENUNITi Normal Sensor value unit, e.g. "C"8.13.3.1 Sensor values table
The sensors values table has to contain a single entry that corresponds to the barometric pressure.
8.13.3.2 Serial port
The serial port to access the barometer device is preconfigured as follows:
Baudrate = 9600, CharBits = 7, StopBits = 1, Parity = 1 (even).
8.13.4 OMEGA CN76000 Temperature Controllers (icbSEN_CN76000)
This ICS software device allows to access up to 16 OMEGA CN76000 temperature controllers connected to a single serial port. Each OMEGA CN76000 temperature controller must have a unique address `x' (see below). Each controller can report two values: current value and set value.
8.13.4.1 Sensor value hardware address
The hardware address must have the format `xy', where `x' identifies the OMEGA controller, and `y' the value to be retrieved:
E.g. address 30 means to access the current value of the 3. OMEGA controller.
The retrieval of values is more efficient, if all values of the same OMEGA controller `x' are placed one below the other in the sensor values table.
8.13.4.2 Serial port
The serial port to access the OMEGA CN76000 temperature controllers is preconfigured as follows:
Baudrate = 9600, CharBits = 8, StopBits = 1, Parity = 0 (none).
8.13.5 ESO Cabinet Cooling Controller (icbSEN_COOLING)
This ICS software device allows to access a standard ESO Cabinet Cooling Controller. The cooling controller can report 4 temperatures, 3 flow rates and one aux. sensor (usually the cabinet open sensor).
The cooling controller has a digital alarm signal. This signal is normally connected to a digital I/O board and must be retrieved with a icbSEN_DIGITAL software device.
8.13.5.1 Sensor value hardware address
The hardware address accepts the values specified in the table below.
Normally, the acronyms specified in the table are used, where <x> is a letter (A..C) and <n> a number that identifies the cooling controller (the software device is usually named INS.SENSORi.DEVNAME = "CCC<n>").:
8.13.5.2 Serial port
The serial port to access the ESO cabinet cooling controller is preconfigured as follows:
Baudrate = 9600, CharBits = 8, StopBits = 1, Parity = 0 (none).
8.13.6 Digital Sensors (icbSEN_DIGITAL)
This ICS software device allows to access digital input signals connected to one VLT standard digital I/O board. The digital board is identified with the INS.SENSORi.PORT keyword, the individual signals are registered in the signals table described below.
8.13.6.1 Sensors update period
The update period specifies the update frequency of the signal values [msec].
8.13.6.2 Signals table
The signals table describes the individual digital signals monitored by the software device.
Apart from the items already described in the first part of section 8.13.1.3, the table has the following keywords:
If no INS.SENSORi.SIGVALi keywords are used and if the width of the signal is 1, then the signal is reported as a logical value, otherwise (width > 1) the sensor is reported as a numeric value.
The value of signals (up to 2 bits wide) can be reported with status strings. In this case, the status strings have to be registered with the INS.SENSORi.SIGVALi keywords, as follows:
When signal j has value k, the status text registered in INS.SENSORi.SIGVALjjk is reported in the status vector of the software device OLDB point.
Situation: Two digital signals are used to report if an instrument enclosure is closed or open. When both digital signals are 0, the enclosure is closed, otherwise it is open.
Solution: Both digital signals are fed as a single 2 bit signal into a digital I/O board (bits 59 and 60). The corresponding digital sensor table entry is configured as follows:
8.13.7 Humidity Sensor (icbSEN_HUMIDITY)
This ICS software device allows to access a VAISALA humidity sensor connected to a serial port. The humidity sensor reports 3 values: temperature, relative humidity and dew point.
8.13.7.1 Sensor values table
The hardware address accepts the values specified in the table below.
Normally, the acronyms specified in the table are used.
Humidity Sensor Values Address Acronym Description Unit 0 EHST Humidity sensor temp. C 1 EHRH Relative humidity. % 2 EHDP Dew point. C8.13.7.2 Serial port
The serial port to access the humidity sensor is preconfigured as follows:
Baudrate = 4800, CharBits = 8, StopBits = 1, Parity = 0 (none).
8.13.8 HERAEUS QUAT10 Temperature Sensors (icbSEN_QUAT10)
This ICS software device allows to access 16 HERAEUS QUAT10 temperature sensors connected to a serial port.
8.13.8.1 Sensor values table
The sensors values table is filled according to the connected QUAT10 temperature sensors.
8.13.8.2 Serial port
The serial port to access the barometer device is preconfigured as follows:
Baudrate = 4800, CharBits = 8, StopBits = 1, Parity = 0 (none).
8.14 FINE TUNING
8.14.1 Timeout Values
A common point of trouble during the configuration is the setting of the different timeout values. It is probably better to set the timeout values bottom up, as e.g. the timeout values of the ICS LCU Server depend of the time that the slowest instrument function needs for a movement. This section lists the different timeout values that have to be configured within ICS. Some timeout values are not placed in any ICS configuration file: if you need to change the default value of any OLDB attribute listed below, please let us know. All values are in msecs. unless otherwise noted.
Timeout for all commands sent to the ICS device manager, except for the commands that use timeout2 listed below (default: 15000 msecs.).
Timeout for the commands ONLINE, SETUP, SIMULAT, STOP and STOPSIM sent to the ICS device manager (default: 120000 msecs.).
MCM access/pollAck timeout. See MCM documentation for details (default: 5000 msecs.). VLT instruments do need to touch this attribute. The NTT instrument EMMI should set this attribute to 15000.
When the ICS LCU server receives a command for several components, it forwards one command for each component to the ICS device manager. The interval value specifies how much the ICS LCU server sleeps between sending each command. The ICS LCU server sends first all commands, then it waits for all replies (default: 1 msecs.).
8.14.2 Software Device Monitoring Task
ICS Optional Configuration Keywords Sec. Keyword Type Description INS.CON.MONTIME Normal Standard device monitoring period [msec].The INS.CON.MONTIME value specifies the speed how the ICS monitoring task updates the status of all ICS software devices. The update is done in a round-robin fashion, however moving devices are skipped by the monitoring task (it is assumed, that a moving device is already updating its status). Note that MCM updates the status according to its own automatic monitoring period (see [14]). The default value of INS.CON.MONTIME is 60000 msecs.
8.14.3 Moving Software Devices In Parallel
ICS Optional Configuration Keywords Sec. Keyword Type Description INS.CON.MOVEMAX Normal Max. number of devices moving in parallel.By default, all ICS software devices are moved in parallel. If this loads the ICS LCU too much, then the number of ICS software devices that are moved at the same time can be limited with the INS.CON.MOVEMAX parameter.
8.15 ICS ASSEMBLIES
8.15.1 Assembly Name
Name used to address the assembly in all commands.
8.15.2 Assembly Value
Value of the assembly, in conjunction with a SETUP command.
8.15.3 Conversion string
The string "<assembly name> <assembly value>" is converted into "<conversion string>" for further processing.
The character "," is used as delimiter for a sequence of commands.
8.15.4 FITS header flag
By default, the current value of assemblies is not stored in the FITS header (the only exceptions being INS.MODE and INS.PATH, see 7.5.5.1 and 7.5.5.2). This can be changed by assigning the value T to this keyword in the configuration file.
8.15.5 Example
8.16 ICS SELF-TEST
ICS Self-Test Keywords Sec. Keyword Type Description INS.TEST.COMMANDi Normal Command to be issued. INS.TEST.PARAMi Normal Command parameters.8.16.1 Command
All commands are sent to the ICS WS front-end process (xxiControl) in the same order as indicated by the index of COMMANDi.
8.16.2 Parameters
All parameters which have to be sent with the command.
8.16.3 Example
results in sending to xxiControl the sequence of commands:
1ICS software devices that access two motors use similar keywords, e.g.: <prefix>.X1ENC and <prefix>.X2ENC to specify if the first or second motor should be moved.
Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |