| |
|
|
|
2.14 ALARM SYSTEM
2.14.1 Purpose
The alarm system is intended to provide the presentation of alarms with acknowledgement handling and the logging of alarm related events.
The alarm system is now supported under CCS_LITE, with some limitations:
A special alarm display is provided with CCS_Lite to replace the Rtap one.
2.14.2 Basic Concepts
Alarm basic concepts listed below are extracted from VLT Software Requirements Specification[14] and VLT Software-CCS Functional Specification[15] documents.
An alarm is a predefined abnormal status of the system, related to a failure situation and signaled by an abnormal event. An alarm becomes active when the system gets into the above status.
The attributes of an alarm are the severity level (fatal, serious, warning), the status (active, inactive, acknowledged, not acknowledged) and the scope (local, i.e. for local user, or global, e.g. all monitoring sites will receive the alarm display).
The utility alrmDisplay must be active to receive and display the alarm notification messages.
The alarm notification message is shown as soon as an alarm becomes active. It disappears when it becomes inactive and an acknowledgment has been given by an authorized user (if so requested). The alarm display reflects the attributes of an alarm. This behaviour is implemented in the alrmDisplay when run in summary mode. See later in this section for a description of the different display modes.
The meanings of the severity levels are:
· Serious: The system cannot perform what it was supposed to do, but there is no need to shut down. Attempts to recover can be performed manually.
These severity levels have been mapped into corresponding states of a state machine implemented within the calculation engine part of the online database.
The statesAlarm activity is controlled by On-line database values. WS applications can directly trigger alarms by writing into the on-line database. LCU applications use their local database; the scan system is in charge of propagating the alarm state to the reporting WS. Alarms are reported in a dedicated window providing an alarm monitoring session. Each time an alarm becomes active, it is reported in a monitoring session. If the alarm scope is global (Available only with full CCS), it is reported in the main monitoring session and all existing local monitoring sessions. If the scope is only local it is reported in the local monitoring session (This is the only mode available under CCS_Lite).
2.14.3 Alarm attributes
2.14.3.1 Severity levels
The basic severity levels are:
In many cases when a process enters a particular severity level an acknowledge of this condition
issued by a human operator is desired. A severity level can be defined as requiring an acknowledge or not. Due to this, the list of severity levels is expanded to:Logically a pseudo severity level is added to the list to represent an inactive alarm:
These severity levels are mapped into states of a finite state transition automatum provided by Rtap as basic functionality for alarms. For a detailed explanation of the automatum refer to Rtap/Plus integration manual. An equivalent mechanism, based on the Calculation Engine and an alarm server process has been implemented under CCS_Lite. Some of the Rtap state machine features, not used in known applications are not implemented under CCS_Lite, resulting in the missing functionality reported in the purpose section.
2.14.3.2 Scope
The scope of an alarm as defined in the basic concepts (2.14.3.2) can be:
2.14.3.3 Alarm type
Depending on the type of process value monitored an alarm can be:
Analog alarms are used to monitor analog process values and discrete alarms are used to monitor discrete process values.
An example of a typical analog alarm is described in figure 1:
An example of a typical discrete alarm is a switch. When is ON, the process value reflecting its status is equal to one. When OFF, the process value is equal to zero. Then a process value of 1 means that it is in Normal severity level. A process value of 0 means that it is in Fatal severity level.
2.14.3.4 Analog Alarm specific attributes
For analog alarms the severity levels are associated with range values. For example the application developer can decide (see figure 1) that if a process value is between 30 and + infinity the alarm should be in a severity level of "Fatal no Ack"; between 0 and 30 "Normal" and between 0 and - infinity "Fatal no ACK.". These range and corresponding severity levels are the main parameters of the alarm definition macros for the analog case. Ranges are specified on the alarm macro definition as a list of decreasing order limit values. For the former example this list is:
A set of N limits define N+1 ranges. The lowest range (in the example 0 to - infinity) is referred as range number 0. Subsequent ranges are referred to range number 1, range number 2,..., up to range number N+1.
Any of the standard severity levels previously defined can be associated with a specific range.
In an alarm there should not be any overlapping of the different ranges. This means that it is not possible to have two severity levels for one range of process values.
The next figure shows an analog alarm with five ranges and four limit values.
To avoid repetitive alarm notification messages in case the process value toggles between two values around a limit, it is possible to define an hysteresis band in which no transition is notified. The value for hysteresis given to an analog alarm represents the size of that hysteresis band.
This size is common to all limits for that alarm point.
The hysteresis band is always considered on the side of the limit located towards the normal range which is defined with the next parameter.
The "hysteresis range" is the number of the range to be considered as the normal alarm state. The hysteresis band is then always applied on the limit side closest to this normal state. See figure 3 for an example.
2.14.3.5 Discrete Alarm specific attributes
A set of N discrete values are associated with a set of N severity levels. As in the analog alarms any severity level can be used for a given discrete value. One severity level is attached only to one discrete value.
Instead of ranges, as in the analog case, for the discrete alarms we have discrete values. For example, if the motor is running, process value is 1 and severity level is Normal, if the motor has stopped, process value is 0 and severity level is "Fatal Ack Required".
On discrete alarms the concept of hysteresis does not exist.
2.14.4 Declarative Interface
Alarms are declared on a dbl database description file through this interface. For this purpose, a set of macros has been provided. These macros are used by the application developer in order to have an alarm associated with a database attribute.
These macros used inside a dbl class or point create an additional alarm control subpoint. In this subpoint the attributes to drive the alarm are defined.
The macros are divided in two groups; analog alarms, discrete alarms. For both groups there are from 2 to 5severity state alarms and each alarm macro has an equivalent which includes a help text and a help file associated to it ( see 2.14.6 on alarm display ).
All alarm attributes are configured via the parameters of the macro.
· alrmDiscrete5stHelp( name, pv, sev1, val1, sev2, val2, sev3, val3, sev4, val4, sev5, val5, sc, tm, ht, hf)
· alrmAnalog5st( name, pv, sev4, lim4-3, sev3, lim3-2, sev2, lim2-1, sev1, lim1-0, sev0, hys, hr, sc, tm ) **
· alrmAnalog4stHelp( name, pv, sev3, lim3-2, sev2, lim2-1, sev1, lim1-0, sev0 hys, hr, sc, tm, ht,hf )
· alrmAnalog5stHelp( name, pv, sev4, lim4-3, sev3, lim3-2, sev2, lim2-1, sev1, lim1-0, sev0, hys, hr, sc, tm , ht,hf )
N.B: Analog alarms with 4 and 5 states are now supported under CCS_Lite.
A name ( name ) should be given to the alarm, following the dbl point naming conventions. This is the name given to the alarm control subpoint created by the macro.
The alarm definition is done inside the class or point which contains the process value ( pv ) to be monitored.
Severity levels ( sev ) are specified with the following macros defined in alarmdefines.db file:
** ACK handling is not supported under CCS_Lite
The maximum number of severity levels ( sev ), defined for a process value , depends on how many ranges ( for analog alarms ) or discrete values ( for discrete alarms ) are considered while designing the specific alarm. The minimum number is obviously two. The alarm definition macros provided can handle from 2 severities up to 5 severities for a specific alarm.
Limits ( lim ) represent the user defined ranges of an analog alarm as explained ( 2.14.3.4 )
For predefined limits, a fixed real number can be used. A database attribute can be use instead of a fixed real number when a dynamic limit is needed. An application can then change the value of the limit at any moment, by writing to the corresponding database attribute. In the macro definition the attribute should be specified using the "alias" database naming convention.
CAUTION: Limits should always be provided in decreasing order. That applies also when limits are defined by means of attributes and values are dynamically changed on line.
Hysteresis ( hys ) and hysteresis range ( hr ) are user defined values as described in ( 2.14.3.4 )
Hysteresis can also be set dynamically via a database attribute,as for limits.
Values ( val ) user defined values for discrete alarms as defined in ( 2.14.3.5)
Timeout ( tm ) is the timeout value in seconds. Used to redirect local alarm to the main monitoring session when the timeout has expired. This parameter is ignored on this release.
Specific arguments for alarms with help :
( ht ) String of a maximum of 128 characters. Help text, to be used in the display application see 2.14.6.
( hf ) String with a filename containing the help file associated to the alarm to be used on the display application, see 2.14.6. alrm files should be placed under the ALARMS module subdirectory and are only text files.
2.14.5 Examples
a) Global, analog two severity level alarm with hysteresis and help.
A motor temperature below 37 degrees is NORMAL and more than 37 degrees is FATAL requiring ACK.
The hysteresis bandwidth is 3 degrees and is applied towards range 1. This means that the temperature can move from 37 up to 40 without an alarm being issued by the system.
If the hysteresis range number had been 0 instead of 1 then allowed variation is between 34 to 37 degrees. See figure 3. This alarms contains also helps ( text and file ).
ATTRIBUTE bytes16 text1 "Motor Class"
ATTRIBUTE bytes32 text2 "Example of Alarm.."
ATTRIBUTE bytes32 desc "Analog Alarm Test"
alrmAnalog2stHelp( "TEMP", temp, FATAL_ACK, 37, NORMAL , 3, 1 , SCOPE_GLOBAL , 0, "Electric Motor Temperature", "Motor.hlp" )
If the limit is dynamically changing then the alarm definition limit field should reference the database value which holds the limit. In this case the alarm macro will look like :
alrmAnalog2st( "TEMP", temp, NORMAL, [<alias>tlimit], FATAL_ACK , 3, 1 , SCOPE_GLOBAL , 0 )
Where [<alias>tlimit] is the database alias of the attribute where the limit temperature is stored. Applications may dynamically change the attribute value leading to an automatic change on the alarm behavior.
b) Local, analog five severity level alarm with no hysteresis and no help.
Water temperature on a heating device. The following schema explains the desired behavior for the alarm.
ATTRIBUTE bytes16 text1 "Heating Device"
ATTRIBUTE bytes32 text2 "Example of Alarm.."
ATTRIBUTE int32 temperature 35
ATTRIBUTE bytes32 desc "Analog Alarm Test"
alrmAnalog5st("HEAT_DEV",temperature,
FATAL_ACK, 100, WARNING, 80, NORMAL ,20, WARNING, 0, FATAL, 0, 0, SCOPE_LOCAL, 0 )
In this case where there is no hysteresis the parameter ( hys ) is zero. The hysteresis range number can be any of the valid ranges because it is meaningless in this case.
c) Global, discrete two severity level alarm, with help.
A light switch. A switch status of 1 means ON and is the normal state. A switch status of 0 means OFF and is considered a WARNING requiring ACK.
ATTRIBUTE bytes16 text1 "Light Class"
ATTRIBUTE bytes32 text2 "Example of Alarm.."
ATTRIBUTE bytes32 desc "Discrete Alarm Test"
alrmDiscrete2stHelp( "SW", swstat, NORMAL, 1,WARNING_ACK, 2,SCOPE_GLOBAL, 0,"Light alarm", "LightHelp.hlp" )
d) Local, discrete four severity level alarm, with no help.
A communication device with three output lines. If the three lines are OK then the process value is 3, and is NORMAL. With two lines working, the process value is 2 and the severity level is WARNING. With only one line working the process value is 1 and the severity level is SERIOUS. Finally with all lines down the process value is 0 and the severity is FATAL ACK. required.
ATTRIBUTE bytes16 text1 "Comm Dev Class"
ATTRIBUTE bytes32 text2 "Example of Alarm.."
ATTRIBUTE bytes32 desc "Discrete Alarm Test"
alrmDiscrete4st("COMM_LIN", commLines, NORMAL , 3 , WARNING, 2, SERIOUS, 1
FATAL_ACK, 0, SCOPE_LOCAL, 0 )
2.14.6 Display of Alarms
The display of alarms is done via the standard Rtap display tool for the full CCS version, while a dedicated panel with similar facilities has been added to CCS_Lite. The CCS_Lite version provides some additional functionality like sound support (if hardware allows) and sorting.
This tool can connect to one or more environments(Full CCS Only) to display all alarms in the system. For every defined alarm, a line in the display will show:
Different colors are associated with the different severity levels.
This display can work in two modes: historical or current. In historical mode the lines are not deleted when an alarm changes its severity level. In this case the window will accumulate lines with the history of every alarm. The last line will show the actual situation. In the current mode, old lines are deleted and the operator only sees the actual status for all alarms.
The operator of the alarm display can also dynamically select from the display, which alarms he want to see. For example, he can select all alarms in FATAL severity level or he might want to see all alarms in NORMAL severity level. This is done via the window menu option Filter and can be modified at any moment by the operator. The filters provided by default by the CCS alarm system are:
2.14.6.1 Alarm display under Full_CCS:
Normally the display will start with the filter in All. In the RtapEnvTable of the default CCS environment the alarm display is started. Possible run string entries for the Rtap alarm display are:
To connect to two environments:
To start showing all alarms of env1:
To run the display in historical mode with a maximum of 10 lines
Fatal connect in historical mode to two environments and display only the alarms in Fatal.
For any other special start-up configuration of the display, check the Rtap/Plus Reference manual, volume 1.
2.14.6.2 Alarm display under CCS_Lite:
If the environment name option is omitted, the alarm display will connect to the local environment as defined by the RTAPENV variable.
The CCS_Lite alarm display offers additional sound capabilities. A set of default sound files is provided and installed by the alrm the module in the VLTROOT, but any application can override these defaults by installing new files in the INTROOT.
The file name corresponds to the severity level and the files must be of type [.wav]
normal.wav, warning.wav, error.wav, serious.wav, fatal.wav
When sound is enabled, the file error.wav will be played whenever an alarm notification is displayed for an alrm with severity level = error.
By default, the alarm Display doesn't play sounds when new alarm notifications are displayed. The default can be changed at startup, using the -se option. In that case, the panel checks if sound is supported, and if it is, it will play sounds corresponding to the alarm severity. The sound status is reported by a small icon in the lower right corner of the panel.
The sound menu in the alrmDisplay panel allows to individually enable/disable the playing of sounds for the different severity levels, and to re-initialise the played sounds in case new sound files are installed.
2. Options: To switch between the the two display mode as explained in the Rtap section above. Current mode is indicated in the title bar.
3. Actions: To perform some action on a selected alarm message. To select a message, just click on it whith the left mouse button.
a. Display help: opens a window showing the help file associated with this alarm. The same result can be achieved with a double click on the message with the left button
b. Current Value: Displays the current value of the attribute having triggered the alarm. The value of the attribute might actually differ from the value shown in the display which is taken when the alarm mesage has been notified. A click with the right button on a selected message has the same effect.
a. Initialize: to request the alrmDisplay panel to read again the sound files associated to the different alarm severities.
It is also possible to click on a column header to sort the messages according to that key. A second click will toggle between ascending and descending order. A small grey arrow in the column header indicates the current sorting order. See column severity in the figure above.
2.14.7 Alarm Acknowledgement (Full CCS Only)
Alarms requiring an Ack. are presented blinking. The Ack. action to be performed by the operator is done through this display, first, by selecting the line showing the alarm and then from the menu bar Edit selecting the action Acknowledge. Also in the Edit menu there is an Update option which does not acknowledge the alarm but refreshes the selected line with the newest process value and time.
By default, a line telling the time, and the user id of the operator, is issued on the display, at the moment of Ack.
Following are some views of the alarm display:
a) The main action bar for the display:
b) The alarm display, when all process values are in a Normal severity level:
c) The pipe pressure is Fatal Waiting for Ack.
Note that the line for myPipe.press the color is in red and is blinking.The operator should issue the Ack, selecting the line and selecting the option Ack. from the Edit menu.
d) The pipe pressure is Fatal Waiting for Ack and the display is in historical mode.
2.14.8 Getting help on an alarm.
This facility is optional. In order to be able to display help files "alrmDisplay" should be started. alrmDisplay application has the same parameters as RtapASDisplay and it starts up the standard Rtap alarm display as explained above. Besides that, it start a process which is able to post help files.
To start display ( help file displaying available ) :
To display help file for an alarm:
This will open a text read-only window where the help file for the alarm will be displayed. If no alarm help was defined, a warning message will appear on a window. The alrmDisplay utility should not be run as a background process.
2.14.9 Main monitoring session, local monitoring sessions
Under CCS_Lite, the alrmDisplay doesn't support multiple environment attachment, and thus the local mode is the only one supported, although attachment to single remote environments is supported.
The main monitoring session and the local monitoring session correspond to two different start-up configurations for the alarm display. In the main monitoring session the display should start connecting to all environments and filtering all global scope global alarms. In the case of the local monitoring session it should start-up connecting to the local environment and filtering all alarms.
Other types of behavior can be specified by setting the corresponding start-up parameters for the display.
The corresponding run strings for the main and local sessions ( in the RtapEnvTable ) are:
2.14.10 Programmatic Interface
The programmatic interface is a set of C functions designed to help the application developer to interact with the alarm system.
The CCS alarm server delivers the notifications of alarms to all applications interested in receiving alarms. This API correspond to a constrained and simpler interface to the general Rtap alarm functions. This facilitate the development of the applications and hides generalities and complexities of the Rtap support layer.
The functions should allow an application to:
2.14.10.1 alrmAttach
This function connects an application to the alarm server. When an application start a connection it can select:
These three elements define a connection and are the parameters of the connection function. For user convenience the following structure is used:
// Name of the environment to connect to
const ccsENVNAME *alrmCon_Env;
// Branch of the database to monitor for alarms
const dbSYMADDRESS alrmCon_Branch;
// Severity levels to be signaled
// Returned connection id, after the successful completion of the function
typedef struct alrmCon_ alrmCONN;
This structure given as the first parameter to the alrmAttach call, should be allocated and deallocated by the application.
Follows the prototype of this function:
ccsCOMPL_STAT alrmAttach( alrmCONN *con, ccsERROR * error );
The dbaddress is the branch name from where to receive alarms. In case of connecting only to an specific alarm, the full path name including the alarm name should be given in dbaddress.
The filter_mask allows to select alarms according to some severity level criteria or scope. The flags are "ORed" in order to compose a filter. For example a connection to all local and fatal alarms will be done with a filter:
alrmCON_SCOPE_LOCAL | alrmCON_FATAL
The function returns an alarm connection identification in alrmCon_Id. Normal CCS return values are SUCCESS or FAILURE . An error is indicating the cause of FAILURE is logged on the CCS standard log.
For connecting to all alarms of an environment the branch alrmCon_Branch must be set to the root branch.
An example of use of the alrmAttach function follows:
//Coonects to wsv1, from root branch for the
//FATAL and NORMAL severity level alarms.
con.alrmCon_Filter = alrmCON_FATAL | alrmCON_NORMAL;
For an extended example see alrmApiTest.c on the test
2.14.10.2 alrmParseMsg
The CCS alarm server sends two types of alarm related messages:
Alarm notifications are messages delivered to the application, by the alarm server, when an alarm that belongs to any of the connections established, has became active. More than one alarm notifications could arrive in one standard message.
The connection management messages are delivered when any of the requested connections has been successfully opened, has been closed or the alarm system has shutdown. The request of the connection is done via alrmAttach function. The actual event is signaled to the application with a "connection management" message delivered by the alarm server.
When a message of one of the previously explained types is received by the application, the parsing function should be called to retrieve the relevant information. For user convenience the following general alarm message structure has been defined:
// Environment of the incoming alarm notification
// Point where the alarm has occurred
unsigned char * alrmMsg_Point;
// Attribute where the alarm has occurred
unsigned char * alrmMsg_Attribute;
// Buffer with the actual value of the attribute
unsigned char * alrmMsg_AttrValue;
// AIN of the attribute ( not used in this release )
// Actual size of the attribute
// Severity level of the incoming alarm
// Scope of the incoming alarm
// Timeout of the alarm ( used for local alarm, see )
// Connection identifier of the incoming alarm
vltINT16 alrmMsg_SourceConnId;
// For alarm management messages, indicates what event has occurred
// can be : alrmCONN_OPEN , alrmCONN_CLOSE, alrmCONN_SHUTDOWN
// Full text of the alarm display message.
unsigned char * alrmMsg_Message;
typedef struct alrmMsg_ alrmALARM;
The prototype of this function is:
CCSCOMPL_STAT alrmParseMsg( msgHEADER *msg, alrmALARM *alarm, vltUINT16 *another,
ccsERROR * error );The first parameter is the message received using the CCS function msgRecvMsg. Its type must be either "alarm notification message" or "connection management message".
The second parameter correspond to C structure which will hold all relevant data coming out of an alarm message. The structure is filled by alrmParseMsg.
The third parameter is used to indicate when there was not another alarm notification to parse inside the received message. A standard message can hold many alarm notifications. When a notification was correctly parsed , the attribute name, attribute value and all other alarm attributes are extracted together with the connection descriptor from the message. This information is used to fill the alrmALARM output structure.
When the message parsed is a connection management message the attribute name, value and all other alarm attributes are set to NULL. The connection descriptor is retrieved from the message together with the type of event that has occurred. Possible events are the opening of the connection, close of the connection or alarm system shutdown.
The structure alarmALARM should be allocated and deallocated by the application. The function will fill the corresponding elements.
st = alrmMsgParse(msg,&a,&another,&error);
while ( another == alrmMSG_MORE )
//An alarm notification received
//Look for another notification
st = alrmMsgParse(NULL,&a,&another,&error);
st = alrmMsgParse(msg,&a,&another,&error);
For an extended example see alrmApiTest.c on the test
2.14.10.3 alrmDetach
This function closes a specified connection to the alarm server. Its prototype is:
CCSCOMPL_STAT alrmDetach( alrmCONN *con, ccsERROR * error );
The parameter should be a valid and already opened connection identifier, as returned by the alrmAttach function. alrmAttach and alrmDetach are asynchronous functions. They return immediately after the call. The actual connection or disconnection event is signaled to the application via an "Alarm Management" type message arriving later.
For an example see the alrmAttach description.
2.14.11 Alarm Logging
All severity level changes occurring to an alarm are logged in the CCS logs. All severity level changes occurring to an alarm are logged in the log file. It logs an entry for every change. The time, the severity level and the attribute being monitored are written. When an alarm is acknowledge by the operator, the user id of the operator is written in the log file together with the time when the Ack. was issued. An example of the logged output follows:
Date Time Environ Module Process
95-09-05 13:04:25: wsv1 alrm alrmLogger HEAT_DEV.Temperature=47 Normal
95-09-05 13:04:25: wsv1 alrm alrmLogger HEAT_DEV.Temparatute= 55 Warning
95-09-05 13:06:20: wsv1 alrm alrmLogger HEAT_DEV.Temperature= 62 Fatal Ack
95-09-05 13:06:31: wsv1 alrm alrmLogger HEAT_DEV.Temperature, user = rabuter Acked
95-09-05 13:06:31: wsv1 alrm alrmLogger HEAT_DEV.Temparature =43 Normal
To run the alarm logger for connections on <env1>,<env2>,..,<envn>:
2.14.12 Configuration
To support the alarm system the following processes should be started in the corresponding environments:
The parameters for this process are specified on the default CCS or RtapEnvTable. If no alarms are defined on a given environment then all alarm related entries on the environment table could be commented out.
Also, the CCS default database configuration contains a CCS alarm branch. In this branch all the behavior implemented in the alarms is codified in terms of a state transition table which drives all alarms in the system.
2.14.13 Reference
· alrmDiscrete5stHelp( name, pv, sev1, val1, sev2, val2, sev3, val3, sev4, val4, sev5, val5, sc, tm, ht, hf)
· alrmAnalog5st( name, pv, sev4, lim4-3, sev3, lim3-2, sev2, lim2-1, sev1, lim1-0, sev0, hys, hr, sc, tm )
· alrmAnalog4stHelp( name, pv, sev3, lim3-2, sev2, lim2-1, sev1, lim1-0, sev0 hys, hr, sc, tm, ht,hf ) **
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
