| |
|
|
|
5 TUTORIAL: IMPLEMENTING ICS FROM SCRATCH
This chapter is intended to help programmers, who are starting from scratch with the implementation of ICS for a new instrument, to implement a working ICS prototype for their specific instrument. Even experienced developers are encouraged to use this tutorial as a checklist, to avoid missing some minor points in the implementation of ICS.
5.1 ROADMAP
The implementation of an ICS consists of the following main steps:
5.2 INSTRUMENT IDENTIFIER AND SOFTWARE MODULE PREFIX
The instrument identifier (e.g. `UVES', represented with `XXXX' or `NNNN' in this document) and the software module prefix are widely used in the instrumentation software to identify files, processes, classes and data items related to the instrument.
The software module prefix are the two first letters of the instrumentation software modules (e.g. `uv', represented with `xx' or `nn' in this document). You have to select a two letters prefix, which is not reserved yet by any other instrument. The prefix is usually the network subnet name assigned to the instrument, as listed in [12], section 5.1; however, it is important to agree this prefix together with ESO: once selected, this prefix can not be modified.
5.3 CREATING FROM SCRATCH A NEW INSTRUMENTATION APPLICATION
Retrieve the Template Instrument software modules and manuals as specified in [23].
Create a new Instrument application package following the instructions in the Appendix of the same document, and using ID and prefix defined in 5.2.
5.4 PREPARING THE USER MANUAL
The Template Instrument Software User Manual can be used as template for your own Instrument User manual. See [23] for details.
5.5 DEFINING A BASIC ICS CONFIGURATION
The complete ICS configuration is kept in a set of FITS keywords stored in a configuration file and in MCM OLDB backup files. Please read the beginning of the Configuration Guide (chapter 8) to understand how ICS configuration works.
A certain subset of the ICS configuration is needed for the Base ICS generic servers to be able to initialize themselves and for the ICS LCUs to be able to boot correctly. This subset consists of the design config. parameters described in section 8.4.1. The individual design config. parameters are described along the rest of the Configuration Guide. They are listed below again for convenience. It is recommended to register these design config. parameters in your NNNN User Manual, before starting with the implementation of ICS itself.
5.5.1 General Instrument Configuration
5.5.2 Workstation and LCU Environments
The instrument workstation environment should have the same name as the instrument workstation itself, while the LCU environments have the same name as the target LCUs. The names of these environments should be listed in [12].
5.5.3 List of ICS Software Devices
The main step in the basic ICS configuration, is to identify the ICS software devices into which the instrument should be split, specifying for each device:
These items are explained below in more detail.
5.5.3.1 Devices and device types
As a general rule, a device has the following characteristics:
2. A setup operation can be addressed through one or more setup keywords. Different devices should NOT be addressed through the same keyword: if this is the case, they should be better treated as one single device or as an assembly (see 7.5.5).
A sound design should foresee devices which are neither too complex (e.g. 10 motors controlled by the same device) nor too many (e.g. 50 temperature sensors, one device each).
Examples of devices types are:
· Motorized devices. They normally control one motor, but there are exceptions. For example the two jaws of one slit may be controlled by separate motors, and they both are addressed by the same setup keyword (INS.SLIT.WID); therefore they are part of the same device.
· Sensor devices (typically, but not only, temperature sensors). The instrument may have plenty of sensors, whose values have to be monitored periodically. In order to avoid to define too many devices, sensors are grouped by hardware port, e.g. all sensors read from the same port (e.g. one serial port) are grouped into one device.
Base ICS supports several ICS software device types: they are listed in section 8.10.1:
The Template Instrument (see [23]) includes one sample of each standard devices supported by Base ICS.
5.5.3.2 Lamps and shutters
Identify all lamps in your instrument and register their characteristics in the User Manual:
Next, do the same for all shutters. The device type should be icbSHUTTER and the FITS prefix: INS.SHUT1, INS.SHUT2, and so on.
Examples available in the Template Instrument (see [23]): devices lamp and tsh
5.5.3.3 Motorized devices
Identify all motorized devices of your instrument. Assign them a device type according to its characteristics (see section 8.12).
Register all motorized devices in your manual, taking care of using the FITS prefix assigned to the device type (see section 8.10.1).
If you wish, keep already track of the MCM OLDB class of the motor (see [14], section 4.2) and the number of element positions the motor has (if applicable, e.g. in filter wheels). These two items will be registered later in the individual device configuration (in section 5.5.3.6 below).
Examples available in the Template Instrument (see [23]): devices adc, dpor, drot, filt, grat, mirr, iods, gris, focu, rot, dekk, slit, slits, tilt.
5.5.3.4 Sensor devices
Identify the channels (or ports) used to access all sensors:
Note that only one type of devices can be connected to a single serial line (e.g. connecting a barometer and a humidity sensor to the same serial line is not supported).
One digital I/O board can be shared between lamps, shutters and sensors. The digital sensor device will manage only the input signals assigned to sensors, without touching the lines associated to the lamps and shutters.
Assign a sensor device to each channel, according to the sensor types connected to it (in case of serial lines) or according to the type of channel (in case of a digital sensor use the icbSEN_DIGITAL type). Register these devices in your User Manual. There is no need to register a FITS prefix; later on, an individual FITS keyword will have to be assigned to each sensor value.
Examples available in the Template Instrument (see [23]): devices fcs, baro, fctc, ccc1, dis1, ench, temp.
5.5.3.5 Special devices
If a specific hardware component is not supported by any of the standard Base ICS software device types, then you will need to write a special software device to access this specific instrument hardware.
Register these devices in your User Manual.
If this is the first ICS you implement with Base ICS, then you might want to continue without the special device; you can add it later to ICS.
Refer to the tutorial in chapter 6 for the implementation of the special device.
Examples available in the Template Instrument (see [23]): device yyyy
5.5.3.6 Define some specific device characteristics (Prepare the User Manual)
Prepare the User Manual for registering the configuration of the individual ICS software devices.
For each motorized device, register at least the associated MCM OLDB class (see [14], section 4.2) and the number of element positions the device has (if applicable, e.g. in filter wheels).
Note: In theory, there is no restriction of what MCM OLDB class is used with what ICS software device type. The MCM OLDB class is selected according to the type of motor hardware, the ICS software device type is selected according to the optical function the motor moves.
5.5.3.7 Assign LCUs to the devices, check FITS prefixes
If not already done, decide what devices will be controlled by each ICS LCU. Register this in the User Manual.
Check the FITS prefixes of all devices:
5.6 ADAPTING THE TEMPLATE MODULES TO A NEW INSTRUMENT
This section assumes that a copy of the Template Instrument, with the ID and prefix defined for your Instrument (see section 5.2) has been created (see section 5.3).
This section describes module by module how to adapt the modules to your specific instrument. In the examples shown it is assumed that your Instrument has ID NNNN and prefix nn.
5.6.1 Module dicNNNN
Module dicXXXX contains the instrument FITS dictionaries.
The ICS FITS dictionary is defined with help of an auxiliary file: dicNNNN_ICS.txt. In theory the sample file can be used as it is, in practice, it is recommended to at least delete the FITS keywords not used by the instrument: e.g. if the instrument does not have a derotator, then all INS.DROT.* keyword entries should be removed.
If the instrument uses special FITS keywords (e.g. for a special device), then these keywords have to be registered in the dicNNNN_ICS.txt file.
5.6.2 Module nni (ICS/nni)
Workstation and LCU OLDBs have the same structure, however LCU OLDBs contain only the parts needed by that particular LCU, i.e the PROCESSES branch contains only one LCUi point and the DEVICES branch contains only the devices managed by the LCU. Each of these device points contains the characteristics of that particular device.
The DEVICES branch has to be manually specified by the developer. One *.db file needs to be created for each LCU (nniEnv1.db, nniEnv2.db, etc.). Each nniEnvi.db file should specify only the devices managed by that particular LCU. All nniEnvi.db files are used to create the WS OLDB. This assures that the WS OLDB contains all device points in the DEVICES branch, while each LCU OLDB contains only the devices managed by that particular LCU.
The nni module contains two files (nnEnv1.db for LCU 1 and nnEnv2.db for LCU 2) that should be modified as follows:
a. From your Instrument User Manual (see section 5.5.3 before), identify all devices that are managed by each LCU, starting from LCU 1.
c. For each new device identify the type and add the corresponding point, as done for the corresponding sample device of the template instrument, paying attention of assigning the device name to the alias of the device point. The alias of a device point must correspond to the corresponding device name in uppercase.
d. Note that motorized devices need a MCM branch for each associated motor. Copy the entries used by the sample devices, but use the MCM OLDB class required by your instrument.
e. Define the device characteristics by editing the attribute values within the device point, as done for the corresponding sample device.
f. Special devices not belonging to any of the types supported by Base ICS should include the corresponding nnidevYYYY.db file (leave this line commented out until the special device is implemented).
g. Repeat points a. to f. for all LCUs. If your Instrument uses one LCU only, delete nnEnv2.db; if instead it uses more than two LCUs, new nnEnv3.db, nnEnv4.db etc. files must be created.
The WS simulator needs to know which OLDB attribute it has to use to read/write the current value corresponding to each FITS keyword associated to each ICS software device. The table dataref in file nniSIM_CONTROL.class is dedicated to this purpose.
This table must be adapted to the actual set of devices present in your Instrument. Therefore, for each of your ICS devices, add the corresponding entries, following the example available in the same table for the device of the same type inherited from XXXX. At the end, remove all entries inherited from XXXX, and which are not pertinent to your Instrument.
In the module Makefile update the DBL_BCF line according to the number of LCUs you have (nniEnvi entries).
The scan links needed by each ICS LCU are defined in the files lnnics1.scan, lnnics2.scan, etc. One file for each LCU has to be prepared.
Replace the entries for each sample device with the entries needed by the devices of the new instrument. Use the sample device entries of the same device type as templates.
5.6.3 Module nnidev (ICS/nnidev)
Module nnidev is only needed if the instrument has a special device. If the instrument does not have any special device, then delete it. Otherwise refer to the tutorial in chapter 6 for the implementation of the special device. If this is the first ICS you implement with Base ICS, then you might want to continue without the special device; you can add it later to ICS.
5.6.4 Module nnins
Module nnins is the integration module of the complete instrumentation software of the instrument, therefore, the module may contain files not related with ICS. From ICS point of view, the following files need to be updated:
One environment template directory is needed for each RTAP and LCU environment. Make sure that there is one environment defined for each LCU used.
If several instruments share the same WS environment, then include a icbConfigGet call for each instrument.
If the LCU controls a special device, then the corresponding software module (e.g. nnidev) has to be loaded just before the icb module in the bootScript file of the LCU.
The template bootScript file may contain lines related to the software module nnidev. If this module is not needed, then remove the nnidev related entries.
5.6.5 Module nnmcfg (MS/nnmcfg)
Module nnmcfg contains the instrument configuration files.
1. The configuration file xxmcfgINS.cfg should be updated according to the configuration described in your NNNN User Manual. To at least be able to boot the ICS LCUs it is needed to register here all design config. parameters, as described in section 5.5.
2. One nnmcfgMOTOR.dbcfg file is needed for each motor driven by MCM. Initially, create an empty file for each motor. The MOTOR name is the associated ICS software device name with a `M' appended, e.g. the MCM configuration file for the filt device is: nnmcfgFILTM.dbcfg.
Note for xxmcfgINS.cfg: If you have two slits (device dekk of type icbMOT_SLIT2_LEN and device slit of type icbMOT_SLIT2_WID) that should accept FITS keywords with the same prefix (e.g. INS.SLIT1.LEN to position device dekk and INS.SLIT1.WID to position device slit), then use the FITS prefix INS.SLIT11 for device dekk and INS.SLIT12 for device slit (i.e. add a digit to the original FITS prefix to differentiate both devices). Using different FITS prefixes for the configuration file allows to store the individual configuration of each device. Use the INS.SLITi.PREFIX keyword in each device to specify the FITS prefix that should be used for SETUP and STATUS keywords, i.e. INS.SLIT1.
5.7 INSTALLING AND TESTING ICS
It is possible to install and run ICS for the first time, when at least:
1. You have defined a basic ICS configuration as described in section 5.5 and registered it in the xxmcfgINS.cfg file.
5.7.1 Installation
Install ICS as described in section 10.2, basically:
5.7.2 Testing ICS
Run and test ICS as described in sections 3.2, 4.6 and in [23].
During development it is recommended to set the INS.CON.ONLINE keyword to False, to avoid that the sensor devices go immediately ONLINE after booting and complain about the (yet) missing configuration or missing hardware (see section 8.9.2).
5.7.3 Restrictions while only the Basic ICS Configuration is defined
Note that if you have defined only the basic set of configuration parameters in the xxmcfgINS.cfg file (usually the first time you run ICS), then the ICS LCUs should boot and the ICS WS processes should start up, but ICS will be able to work only in a limited way due to the missing configuration items:
· ICS has to run in simulation (at least HW simulation), because ICS does not know yet how to access the hardware (if the individual ICS software device configurations are missing).
· If e.g. the element names of a filter wheel are not registered yet, then the wheel can only be moved to an index position (even in simulation), e.g.
· If e.g. the ranges of encoder values corresponding to each filter wheel position are not defined yet (in xxmcfgFILTM.dbcfg using motei) or are overlapping, the current position of the device, as reported in the reply to a STATUS command and in the OLDB may not be correct.
5.7.4 Processes
In an ICS LCU, at least the following two processes should be running after the LCU has booted:
The following two WS processes should be running after starting them (xxinsStart -proc ICS):
5.8 IMPLEMENTING THE ICS STAND-ALONE PANEL
In order to make the operations more user friendly, a basic GUI panel should be implemented before configuring the individual ICS software devices.
At present the Template Instrument is not providing any example of such a GUI.
5.9 CONFIGURING INDIVIDUAL ICS SOFTWARE DEVICES
Once the basic ICS configuration is correct and the ICS WS and LCU processes are running, the next main task is to define the individual configuration of each ICS software device.
Each device can be configured and tested individually, however, as the $VLTDATA/config/lnnicsi.dbcfg files need to be updated each time the xxmcfgINS.cfg file is updated (running the icbConfigSet utility), it is recommended to always configure a reasonable set of devices at the same time (note that you also need to reboot the LCU if you update the list of software devices).
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.
The procedure to update the ICS configuration is described in section 8.5.3.
5.10 WRITING SPECIAL ICS SOFTWARE DEVICES (if needed).
See the tutorial in chapter 6.
5.11 FINAL REMARKS
1. At the end, when ICS is aprox. stable, it is recommended to archive all ICS software modules (cmmArchive), delete (or rename) the main ~/NNNN directory and test if ICS can be rebuilt and installed correctly from the Software Archive as described in section 10.2.
2. The NNNN User Manual should be checked and completed, specially the configuration described in Configuration Guide should reflect the final configuration of ICS.
1Note: The acronym is used a.o. as the OLBD device point alias. If several ICSs are installed in the same instrument workstation, then the devices of all ICSs must have different acronyms. If necessary, prefix the acronym with the instrument module prefix, e.g. XX_TEMP.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|