6 TUTORIAL: CREATING A SPECIAL DEVICE
This chapter is intended to help programmers to implement a working ICS software device for their specific instrument. Experienced developers are encouraged to use this tutorial as an implementation guide, to avoid missing some minor points in the implementation.
Every instrument has its own peculiarity. It is therefore to be expected that every instrument has to define and implement the control code for some not standard devices, or that it has to define a partly different behavior of a device with respect to the standard. The following sub-sections explain what has to be done.
6.1 ROADMAP
The implementation of an ICS software device consists of the following main steps:
6.2 RETRIEVING THE SPECIAL DEVICE TEMPLATE
Assuming that you have followed what described in section 5.3, you must have, under the directory NNNN/ICS, a module called nnidev, containing the special device example provided by the Template Instrument.
Copy this module as many times as needed (one module for each special device foreseen), selecting a different software module name for each special device (replace nnidev above with another name starting with `nni').
6.3 UPDATING THE ICS MANUAL
Register the special device in the NNNN User Manual. Add a description and specify the reason why this ICS device has to be implemented as a special device.
Repeat the above for each additional special device.
6.4 BASIC SPECIAL DEVICE CONFIGURATION
The basic configuration of a special device consists in the configuration needed to integrate the special device into the rest of ICS, without implementing the particular code of the special device. The following has to be decided:
3. Names of the FITS keywords associated to the device, in particular the FITS prefix (e.g. INS.OPTI6). If the special device is a sensor, then the FITS keywords associated to each sensor value have to be defined.
The nnidev software module has to be adapted as follows to register the basic configuration:
a. Replace the strings `yyyy' and `YYYY' with the name of the special device, as already specified above, except the value of the prefix attribute.
b. Set the value of the prefix attribute to the FITS prefix associated to the device, as you have documented in the NNNN Manual.
d. Set the value of the devType attribute to the name of the software module plus the device name in uppercase, e.g. "nnidevYYYY".
e. Set the value of the server attribute to the name of the server that will manage the special device, usually the software module name followed by "Server", e.g. "nnidevServer".
Repeat the above procedure for each additional special device.
6.5 INTEGRATING THE SPECIAL DEVICE INTO ICS
To integrate a special device YYYY implemented in module e.g. nnidev, proceed as follows:
Include the nnidev.db file in the nniEnvi.db file of the LCU that will control the special device. E.g. add the following lines at the end of file ICS/nni/dbl/nniEnv1.db:
Add the necessary information to the dataref table in nniSIM_CONTROL.class (see section 5.6.2 point 2.).
Add the special FITS keywords associated to the special device to the file dicNNNN_ICS.txt (if any).
of the LCU that will control the special device (with utility vccEnv). The software module should be registered before the icb module. Update this file in the environment template located in the nnins module:
Repeat the above procedure for each additional special device.
You may wish to rebuild and reinstall ICS to test that the ICS processes recognize the new special device(s). The ICS processes should find the OLDB point of the special device(s) in the DEVICES branch when they start and integrate the device(s) into ICS.
6.6 ADAPTING THE TEMPLATE SOFTWARE
This section assumes that the special device software module has already been adapted and tested as described in sections 6.2 to 6.5. Now the behavior of the special device, in particular it's interface to the hardware, has to implemented.
This section assumes that the special device is called YYYY and that the associated software module is called nnidev.
6.6.1 On-line database
The device characteristics and special attributes needed by the special device must be defined in the special device OLDB point. Edit file nnidev/dbl/nnidevYYYY.db as necessary.
6.6.2 Command Hooks
The template provides the necessary interface to the CI (Command Interpreter). The supplied code unpacks the parameters received by the commands and supplies a function hook for each command. These hooks are in the file nnidevDeviceCmds.c.
Some details related to the current xxidev template:
· The nnidevDeviceStatus() hook provides parameters flag, conflog, opslog and condlog. All these parameters should not be used.
· The supplied nnidevDeviceSetup() and nnidevDeviceStatus() hooks are examples. They write/read to/from two OLDB attributes. Replace this code with the code needed by your own device.
The rest of the template source files normally do not need to be modified.
File xxidevDeviceDummies.c contains obsolete commands, that are expected not to be needed.
Files xxidevServer.c and xxidevDeviceNewObj.c contain the initialization code of the device.
File xxidevServerInterface.c contains code that interfaces the CI with the command hooks.
6.6.3 Implementing a Control and/or Monitoring Task
The lcctooTASK described in this section is optional. It may be used to simplify the implementation of control and/or monitoring tasks.
Module lcctoo provides a type lcctooTASK that can be used to implement a control and/or monitoring task. See the lcctooTASK man page for details.
A control and/or monitoring task can be created and started (lcctooTaskNew(), lcctooTaskStart()) in the device LOADED to STANDBY transition (nnidevDeviceStandby()). The SETUP command can update parameters and then call lcctooTaskWakeup() to ask the task to update it's parameters. The task should be stopped in the STANDBY to LOADED transition (lcctooTaskDelete()).
A template for the task function is supplied in the lcctooTASK man page.
6.6.4 FITS Logs
A ICS software device should use FITS logs to log all it's operations. E.g. when the device moves the corresponding SETUP parameters should be logged (logFitsParRecord()) followed by a move event (logFitsEvent()). A FITS log comment should be issued when the movement is completed (logFitsComment()) or an unforeseen event (logFitsEvent()) in case of an error.
Sensor devices should have an option to periodically log the sensor data as a FITS log.
6.7 INSTALLING AND TESTING THE SPECIAL DEVICE
To test a special device, ICS can be installed and tested as usual. Refer to sections 5.7 and 10.2 for details. The LCU should start the server that manages the special device when it is booted (nnidevServer).
6.8 FINAL REMARKS
Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |