4.2 HOW TO CREATE AN APPLICATION ON THE LCU

An application on the LCU accepting commands has an interface to the outside world through the message system.

This interface is supported by LCC through the Command Interpreter (CI). LCU applications shall be based on the CI unless special performance is required. The CI is particularly useful for applications performing many simple independent actions. The CI is a table driven application which is working according to a fixed scheme. Its purpose is to simplify and speed up the development of the application, see the LCC User Manual [2].

The following discussion assumes that the command interpreter is used as the main building block of the processes on the LCU.

The LCU boots and downloads the application software from the workstation. For each process using a Command Interpreter, an initialization process is started which spawns the Command Interpreter, configures and initializes database values and configures I/O signals.

The Command Interpreter (CI) is now ready to receive commands. The Command Interpreter works with two tables, Command Definition table (CDT) and Command Interpreter table (CIT).

The CDT defines the commands, the parameters corresponding to each command, the range of the parameters, the reply etc., see the LCC User Manual [2]. The CIT defines the action on each command. It defines which routine shall be called or which process to spawn on the reception of a command.

4.2.1 Command Interpreter

The Command Interpreter hides all message handling to the user. When the user routine returns the Command Interpreter returns the reply to the command.

The calling sequence is divided in two steps. First the function IxxxWsSt is called. This is only an interface function which unpacks the incoming message buffer. All parameter of the command are packed in one buffer. After the function xxxWsSt has returned, the interface function packs the return values into the return buffer. The function in the example above has no input or return parameters. More examples of interface functions are shown in the LCC User Manual, [2].

The reason to have an interface function which calls the function performing the actual task, is to split the handling of the message buffer and the actual task. This also makes is easier to reuse of the routine xxxWsSt.

The routine xxxWsSt can also be spawned as a task using the same code. In this case you should add a call to ccsInit at the top and one call to ccsExit before returning or alternatively use the option REGISTER in the CIT. In this case the command interpreter performs the ccsInit/ccsExit calls. This option allows you also to specify process name and break and kill handlers for the process. The advantage to use this option is that you can use the same code as for a function, e.g. it is very simple to change a task to a function and vice versa.

The LCC User Manual, [2], also gives examples of using the message system from the function/task.

The error number and optional run-time parameters are expanded by the error system using the ERROR/xxx_ERRORS file.

4.2.2 Creating an LCU Application

The LCU Server Framework, [9], provides a concept and templates for creating LCU applications based on the command interpreter. This is the major entry point which should be used when starting devloping new LCU applications.

4.2.3 LCU Management

The main purpose of the LCU management is to simplify the control of the LCU for coordinating systems on a higher level, e.g. Telescope Control System, Instrument Control System or the complete VLT control system. As an example the function lccWarmStart brings the LCU from the state LOADED to STAND-BY or ON-LINE, sending all necessary commands to all software devices registered, see also the LCC User Manual [2] for more information.

4.2.3.1 LCU States

These states are used to express the degree of availability of the LCU, as seen from higher level, coordinating software. By use of standardized names for the degrees of availability and for transitions between them, the details of an individual LCU need not be known on higher level.

ON-LINE Everything needed to use the LCU for normal operation (normally for observation!) is ready to be used; switched on, initialised, checked etc.
This is the state used for normal night-time operations.

STAND-BY Everything needed to use the LCU for normal operation is in a known and defined status, e.g positions are known (encoders initialised). To come to ON-LINE state, normally no movements are necessary (except perhaps releasing brakes). The transition to ON-LINE is fast (a matter of a few seconds at the most).
This is the state normally used for day-time wait.

LOADED The necessary software is loaded in the LCU, but some software and/or hardware is in an un-determined status (=not initialised).
This is the state where normally no activity can take place, except starting the system (=go to a higher state)

STAND-ALONE Normally all functions of the LCU are ready to be used. This state usually provides the same functionality as ON-LINE. The difference is in the use from higher level software: ON-LINE is used for normal operations, controlled by higher level software, and STAND-ALONE is used for other operations, e.g maintenance, tests, calibrations etc. For this reason, it is perfectly possible that there are functions available in STAND-ALONE which are NOT available in ON-LINE and vice versa, e.g functions to test and tune control loops.
This is the state normally used for test and maintenance.
Observe though that this is not the only state where maintenance can be performed. Many maintenance operations might have to be performed in other states also and should not be restricted to STAND-ALONE only.

The above description of the states is on purpose a bit vague, and is an attempt to define the PURPOSE and the USE of the states, rather than giving an exact and waterproof definition. This should indicate that a great deal of flexibility is allowed, and that each LCU has to define its own situation for each of the states. Of course, the general intentions should be followed!

It is allowed that two states provide exactly the same functionality. If that is the case, the transition between them should ANYWAY be defined according to the LCC rules, even though that transition is just an OK return.

By checking the state of the LCU, the coordinating system knows what operations it can do on the LCU. It knows that if the LCU is in the state ON-LINE, it is operational and can be used by the coordinating system. As all LCUs will also have the same set of states, the coordinating system does not have to know all the details about an LCU system. It knows that in some states only certain actions are allowed. This is particularly useful when the coordinating system controls many LCUs because it can do the same check on all of them.

If the LCU is in any other state, the coordinating system knows that it has to request that the LCU switches to the state ON-LINE before it is allowed to operate it. This might have to be coordinated with other potential users of the LCU.

4.2.3.2 State Transition Functions

The LCC provides functions for transitions between the different states. The LCU Management functions works on software devices. The software device shall normally be based on the Command Interpreter.

The software device shall be defined in the devicesFile. This file defines all software devices handled by the LCU Management module. It defines the name of the software device, the name of the process controlling the software device, the state of the device and if the software device is in simulation.

The LCU Management functions simply works as a command dispatcher sending the appropriate commands to each software device defined. One example is the function lccWarmStart, which is the normal startup function of an LCU. It takes the LCU from the state LOADED to any of the states STAND-BY, STAND-ALONE or ON-LINE.

Before changing state it sends the command INIT to each software device. When all software devices has replied without error it sends the command STANDBY or ONLINE to the software devices, depending on the end state requested. The LCU management functions and their actions are described in the LCC User Manual [2].

In the case defined in section 4.2.1 with a top level process controlling several low level devices, one can very well send all commands to the top level process (including the standard commands INIT, ONLINE etc. to initialize the LCU or to put it in ON-LINE state) and from the top level process call the LCC functions lccWarmStart, lccInitAll etc. to initialize all the devices or to put all the devices in the state ON-LINE. This will also set the global LCC state correctly.

4.2.3.3 Standard Commands

Each software device shall accept a set of standard commands, defined in section 3.1.4. The LCU Management module sends standard commands to the software devices when executing the functions for state transitions. Currently the following commands are defined and sent by LCC to software devices by the LCU Management functions:

· SELFTST to perform a self-test of the software device. Selftest shall be performed on the lowest level only checking software devices, but not moving any hardware.

· the EXIT command is sent before rebooting, e.g. lccColdStart. Before exiting the software device must stop all moving parts and switch off hardware if necessary (corresponding to the commands STOP, OFF and EXIT).

Any software device defined in the devicesFile MUST implement the functions or at least an interface function corresponding to these commands. The commands shall also be defined in the CDT and CIT. There are no rules defining what action must be performed when receiving any of these commands. This must be defined in detail by each application. There can also be commands with no action. The only rule is that for state transition commands (like ONLINE) it must take the software device to the defined state if the command is successful. By defining the complete state of a software device for the global states, the differences between two states also defines what has to be done to transit from one state to another, e.g. the differences between the states STAND-BY and ON-LINE defines what should be done on the command ON-LINE when it is received in the state STAND-BY.

The software device will end in the state LOADED after boot. The software is normally initialized in this state.

The command INIT normally initializes the hardware. Software not initialized in the state LOADED will normally be initialized by the INIT command.

The software device and the hardware it is controlling must have been successfully initialized before the software device can leave the state LOADED with an ONLINE or STANDBY command.

The initialization must be done with an INIT command or can be part of the procedure of the STANDBY or ONLINE command.

The INIT command must be allowed in the state LOADED and can also be allowed in the states STAND-BY and ON-LINE. An INIT shall always bring the software device to the state LOADED at the start of the INIT phase. The INIT command should be followed by a STANDBY or an ONLINE command to put the software device in a defined state.

The STOP command is sent to stop an ongoing activity, e.g. stop a moving motor. It does not make any main state transition.

The following picture defines the states and the transition between states of a software device:

The INIT command from the states STAND-BY and ON-LINE is dashed to show that it is not necessarily allowed in these states.

The state OFF is not shown, because it is not a real state, the software device ends in this state when it no longer exists, e.g. terminates after an EXIT command.

State changes can go directly from one state to another one without having to go through intermediate states, e.g. a device can go from state LOADED directly to the state ONLINE without going first to STANDBY and then to ONLINE.

In case a state transition fails the system must fall back to a safe state. In this case it is recommended to go to the state LOADED.

4.2.3.4 Signal Handlers

Every application shall accept the commands KILL and BREAK. These two commands are not handled as ordinary commands. They are trapped in the message system, which then sends a signal to a signal handler. A process can use the default signal handler or define its own. The signal handler is defined when calling ccsInit, or when starting the command interpreter.