# Presentation: 006452

## Introduction to Alarm Handlers

- Randy Flood
- Karen Schroeder
- AOD/OPS

## What is the Alarm Handler?

- The Alarm Handler is an interactive graphical application used primarily by accelerator operators and physicists to display and monitor EPICS database alarm states.

## Purpose of the Alarm Handler

- Bring alarms to the operator's attention
- Provide the operator guidance for handling of specific alarms
- Allow the operator to globally acknowledge alarms
- Provide a graphical view of current database alarms
- Provide for logging alarms and display of the logged alarm history

## What is an alarm?

- Deviations from tolerance band
- Major: red alarm. Significantly out of tolerance or a fault
- Minor: yellow alarm. Moderately out of tolerance or a warning
- Software or Hardware errors
- Loss of communication to hardware or linked records

## Severity and Status

- 	There are two parts to an alarm: the alarm status and the severity of that alarm status. Alarm status and severity are set and checked whenever a record is processed.

## Severity and Status

**Alarm Severity**
- The SEVR alarm field in an EPICS database record specifies the severity of an alarm state. Currently the alarm severity can take one of the following four values:
- NO_ALARM: The channel is not in alarm. The pv has returned to a normal state
- MINOR: Yellow alarm. This is the lowest alarm severity.
- MAJOR: Red alarm. This is the second highest severity condition.
-  INVALID: White alarm. Invalid data or no communication. This is the highest severity condition.

## Severity and Status

- Each EPICS database record has a STAT alarm field that specifies the alarm state of the database record. Currently the status field can take one of more than 20 values, some of which are:
- HIHI
-  HIGH
-  LOW
-  LOLO
-  STATE

## Runtime Window 

- 	The runtime window is a small icon like window that contains a single button containing the name of the alarm configuration main Alarm Group.
- 	The color of this button is used to show the highest alarm severity of any outstanding alarms.
- 	Beeping and blinking of the button is used to show the presence of unacknowledged alarms.
- 	Pressing the runtime window button will open the Alarm Handler Main Window or, if already open, bring the Main Window to the top of the window stack.

## Masking PV’s

- 	A Mask is a user definable string of 5 characters that tells the alarm handler how each alarm should be handled.
- 	The Mask settings can include any or all of the following:
**C**ancel – If set, the ioc will no longer send alarm information to the alh on this channel
**D**isable – The alh will not beep or display alarms from this channel
- no**A**ck – The alarm condition will flash but not beep
- noack**T **– If set, the alh will stop** **beeping when an alarm clears. Otherwise, even inactive alarms will beep if not acknowledged
- no**L**og – If set, the alh will not record the alarms in the log file

## Configuration Tree Structure Area

- 	Displays the groups in a common tree structure. The order in which the groups are listed in the configuration file is the order they will be listed in the tree structure.
- 	Selecting any group will cause that group’s contents to be displayed in the group contents area (similar to the old Windows file manager).
- 	Clicking on the arrow button will expand/collapse a branch. A summary of Mask settings is also displayed.

## Configuration Tree Structure Area

-   	Active and unacknowledged alarms are displayed using a color code:
- White for INVALID alarms
- Red for MAJOR alarms
- Yellow for MINOR alarms
- The background color for no alarm

## Configuration Tree Structure Area

- 	The alarms are displayed in two columns. Active alarms are in the right column and the left column is for acknowledging alarms. This is also true in the Group Contents area.

## Group Contents Area

- 	The Group Contents area displays the contents of the group selected in the Configuration Tree Structure Area. Again, this works like the old Windows file manager. When the pv level is reached, the branch cannot be expanded anymore and individual pv’s are not displayed in the Configuration Tree Structure Area. For these channels, the current status and severity followed by the highest unacknowledged status/severity will be displayed.

## Message Area

- 	At the bottom of the main window is the message area. The message area is like the legend of a road map. It shows what the mask symbols stand for, group alarm counts, beep severity, and channel alarm data. It also shows what configuration file is being used and gives the option to silence the ALH for one hour or silence the current alarms.

## Related Files

- Alarm Handler Alarm Log File
- ALH-default.alhAlarm
- File where all alarm events will be recorded
- Will log events for all launched alarm handlers in the same file if the the default file is used.
- Alarm Handler Operator Modification file
- ALH-default.alhOpmod
- File where all changes to the alarm handlers will be recorded (e.g., changes to masks, changes to beep severity, etc.)
- Will log events for all launched alarm handlers in the same file if the the default file is used.

## Related Files (Continued)

- Alarm Handler Configuration File
- <name>.alhConfig
- Contains the alarm groups and PV channels to be included and defines the order in which they will be presented.
- Defines how alarms will be displayed and how users need to interact with those alarms.
- Alarm handler always reverts to the settings defined in the configuration file when the runtime window is launched.

**Notes:**
Last bullet – most of the optional configuration instructions can be added or modified once the alarm handler has been launched. These modifications or additions will be lost when exiting from the alarm handler runtime window.

## ALH Configuration File Rules

- Alarm handler commands or instructions are case sensitive.
- A group or a channel must be the first line in a set of commands.
- Optional commands are prefaced with a “$” and only pertain to the channel or group preceding it.
- Comments are prefaced with “#”

## Configuration FileALH Tree Structure

- The alarm handler main group is defined in the configuration file as the null group and is displayed at the top of the alarm handler and in the runtime window.
- An existing alarm handler can be merged into a new one. The “included” alarm handler will appear in the new alarm handler as a group.

**Notes:**
Useful if you have a core set of PVs you always want to monitor in a alarm handler. Maintenance then only needs to be done on one file.

## Configuration FileALH Tree Structure

- Groups can contain other groups and/or channels.
- Channels contain a PV name defined in the EPICS database and are always assigned to a group
- Groups always appear before channels in the main window no matter where they appear in the configuration file.

**Notes:**
Group names cannot have a space in them

## Configuration FileAlarm Aliasing

- A PV can be “renamed” to create a more descriptive entry in the alarm handler using the $ALIAS command.
- The “$ALIAS” name can have spaces whereas a PV name cannot.

## Configuration FileRelated Processes

**A related process can be attached to a group or channel and launched in one of two ways:**
**When operator clicks on a process button which has been defined in a $COMMAND instruction**
**Automatically when the channel transitions to a specified alarm state defined in the $SEVRCOMMAND instruction and the specified transition. **
**	****Ex: $SEVRCOMMAND UP_MAJOR medm –x –attach booster/psApp/BEK.adl would cause the MEDM window to pop up when the alarm state of the process variable would transition from no alarm or minor alarm into the major alarm state.**

**Notes:**
Second bullet transition can be specified as any alarm. Or when a transition is to the alarm state from a specific direction. List is 

## Configuration FileAlarm Guidance

- Alarm guidance information can be attached to groups or channels and is launched by clicking on the “G”  button. Can display information in the form of:
- A text box defined in the configuration file using the $GUIDANCE instruction. This form of guidance must be terminated with the $END instruction.
- A web page defined in the configuration file using the $GUIDANCE instruction followed by the URL address.

## Configuration FileAlarm Masks

- The default Alarm masks are assigned to channels, not groups and define:
- if an alarm is to be displayed
- when an operator must acknowledge the alarm, and
- if the alarm is to be logged.
- The mask(s) has to be defined in the proper place in the mask list <CADTL> to take affect with “-” as place holders for the unused masks.

**Notes:**
An improperly defined mask will default to no mask and will be displayed as  - in the main window

## Configuration FileForcing Alarm Masks

- The $FORCEPV command followed by a channel name changes a group or channel Mask to the forceMask based  on one value of that channel and resets the mask to the defaultMask based on a different value.
- The forceMask is defined in the $FORCEPV command and the defaultMask is defined in the CHANNEL command.

## Configuration FileForcing Alarm Masks

- The $FORCEPV command followed by CALC (instead of a Channel name) changes the mask based on a calculated value
- Can have up to 6 PVs included in the calculated expression.
- PVs included in the calculated expression do not have to be displayed in the alarm handler.
- Calculated expression can be logical, algebraic or relational.

## Configuration FileAlarm Filters

- Alarm filters will prevent the alarm from being displayed unless the Channel:
- remains in alarm for longer than the specified duration (entered in seconds), or
- toggles in and out of alarm a specified number of times in the specified duration.

## And Finally . . .

- Thanks to Janet Anderson and all the individuals and groups who have contributed to developing the alarm handlers.
- Thanks to Steven Jones for his help in preparing this talk.
- More complete information on alarm handlers can be found in the “Alarm Handler User's Guide” by Janet Anderson located on the Web in the Epics Documentation under the Extensions Section.