AlarmHandler.md

Alarm Handler

AlarmHandler is a Tango device server which manage alarms in compliance with IEC 62682 standard. It evaluates the formulas that define the alarm condition and creates a dynamic attribute for each alarm rule to export the state of the alarm. Having the alarm state in the attributes enables asynchronous notification of clients interested in alarm changes, with the granularity of one alarm. In fact, each attribute representing an alarm can push events when its state changes. Clients can subscribe to events of the alarm attributes they are interested in, or the events of all attributes, and be notified asynchronously. Clients can be graphical user interfaces, notifiers, other AlarmHandlers or any TANGO device in general. The configuration of each alarm is saved in the Tango Database as attribute properties.

Configuration

Configuration uses both device/class and attribute properties.

Device/Class properties

Device properties are for configurations that apply to the entire device. The same properties can also be defined as Class properties, in which case they apply to all devices of the AlarmHandler Class in which the Device Property of the same name is not defined.

Name	Description	Type	Default Value
GroupNames	Labels for Group mask, first is for mask 0x00 so ‘none’ is the default label associated to it. Second label is associated to the mask 0x1, third to the mask 0x2, ... Only labels defined here can be used as group names in the alarm configuration.	String[]	none
SubscribeRetryPeriod	Change event subscription period in seconds. Every time this period expires AlarmHandler tries to re-subscribe all faulty attributes	DevLong	30
StatisticsTimeWindow	Not implemented	DevLong[]	60
ErrorDelay	Delay in seconds before going to ERROR state after receiving an exception.	DevULong	30
SetAlarmQuality	Set the alarm attribute quality as evaluated using the attribute quality in the formula	DevBoolean	false

Attribute properties

The following attribute properties are used to store the configuration of alarms. They are present for each attribute that has the same name as the alarm name. Some of these properties are mandatory, others optional.

Name	Description	Mandatory	Default Value
tag	Alarm name (same as the attribute name)	Yes
formula	Alarm formula	Yes
on_delay	Delay in seconds before the alarm becomes active after the formula result has changed from false to true	No	0
off_delay	Delay in seconds before the alarm becomes inactive after the formula result has changed from true to false	No	0
priority	Severity of the alarm. 'highest', 'high', 'medium', 'low', 'lowest','fault', 'warning' and 'log' are allowed	Yes
silent_time	Time in minutes when the alarm will be silenced or shelved with the Silence and Shelve commands. If -1, the alarm cannot be silenced or shelved.	No	-1
group	One or more groups to which this alarm belongs. The possible groups are defined in the device property GroupNames. Multiple groups are specified by concatenating with the | character	Yes
message	Additional message carried with the alarm	Yes
on_command	No	Command executed when the alarm becomes active. Command argin has to be DEV_VOID or DEV_STRING. In the second case the string “name=...;groups=...;msg=…;values=…;formula=...” is passed as the argument	""
off_command	No	Command executed when the alarm becomes inactive. Command argin has to be DEV_VOID or DEV_STRING. In the second case the string “name=...;groups=...;msg=…;values=…;formula=...” is passed as the argument	""
enabled	If true alarm is enabled, otherwise it is set to the OOSRV - out of service alarm state	No	1
receivers	List of alarm states colon list of email recipients. Used only by alarm-notify	No	""

Formula syntax

See Formula.md.

Interface

Attributes

Dynamic Attributes

Name	Attr. type	R/W type	Data type	Description
AlarmState	Scalar	READ	DEV_ENUM Labels: NORM, UNACK, ACKED, RTNUN, SHLVD, DSUPR, OOSRV, ERROR	Dynamically created with the tag name as the attribute name for each alarm

Static Attributes

Name	Attr. type	R/W type	Data type	Description
alarmAudible	Scalar	READ	DEV_BOOLEAN	True if there is at least one alarm that needs an audible indication on the GUI
StatisticsResetTime	Scalar	READ	DEV_DOUBLE	Time elapsed in seconds since last ResetStatistics command
alarm	Spectrum	READ	DEV_STRING	List of active (UNACK or ACKED) alarms and and their status. Format described below
alarmDisabled	Spectrum	READ	DEV_STRING	List of disabled (OOSRV or SHLVD) alarms and and their status. Format described below
alarmNormal	Spectrum	READ	DEV_STRING	List of alarm names in NORM state
alarmUnacknowledged	Spectrum	READ	DEV_STRING	List of alarm names in UNACK state
alarmAcknowledged	Spectrum	READ	DEV_STRING	List of alarm names in ACKED state
alarmUnacknowledgedNormal	Spectrum	READ	DEV_STRING	List of alarm names in RTNUN state
alarmShelved	Spectrum	READ	DEV_STRING	List of alarm names in SHLVD state
alarmOutOfService	Spectrum	READ	DEV_STRING	List of alarm names in OOSRV state
alarmSilenced	Spectrum	READ	DEV_STRING	List of alarm names in silenced state
alarmList	Spectrum	READ	DEV_STRING	List of all alarm names
alarmFrequency	Spectrum	READ	DEV_DOUBLE	List of alarms frequency, i.e. the number of times alarms have occurred since the last ResetStatistics command
alarmSummary	Spectrum	READ	DEV_STRING	List of all alarms and their status. Format described below
eventList	Spectrum	READ	DEV_STRING	List of all attributes subscribed (attributes present in formulas)
eventSummary	Spectrum	READ	DEV_STRING	List of all attributes subscribed and their status. Format described below

• alarm

  <timestamp seconds>\t<timestamp us>\t<tag>\t<ALARM|NORMAL|ERROR>\t<ACK|NACK>\t<priority>\t<silenced time>\t<group>\t<message>
  Example:
  1740990955	124920	pssip_kg09.05_ch1_off	ALARM	ACK	high	0	gr_vac	sip300_l04.05 PS not ON
  1741280601	438811	pssip_ctf.03_ch3_off	NORMAL	NACK	high	0	gr_vac	sip_ctf.07 PS not ON	 
  1741595157	64811	pssip_kg04.01_ch1_off	ERROR	ACK	high	0	gr_vac	Tango error for kg04/vacuum/pssip_kg04.01/stat1: Not valid status

• alarmDisabled

  <timestamp seconds>\t<timestamp us>\t<tag>\t<OOSRV|SHLVD>\t<ACK|NACK>\t<priority>\t<silenced time>\t<group>\t<message>
  Example:
  1740990965	41097	pssip_kg07.15_ch2_off	OOSRV	NACK	high	0	gr_vac	sip75_boc_l02.01 PS not ON	

• alarmSummary

  tag=<tag>;state=<state>;priority=<priority>;time=<date time us>;formula=<formula>;message=<message>;
  Example:
  tag=pssip_kg09.05_ch1_off;state=ACKED;priority=high;time=2025-03-03 09:35:55.124920;formula=(kg09/vacuum/pssip_kg09.05/state1 == 0);message=sip300_l04.05 PS not ON
  tag=pssip_ctf.03_ch3_off;state=ACKED;priority=high;time=2025-03-06 18:03:21.438811;formula=(ctf/vacuum/pssip_ctf.03/state3!=ON);message=sip_ctf.07 PS not ON
  tag=pssip_kg04.01_ch1_off;state=ERROR;priority=high;time=2025-03-10 09:25:57.64811;formula=(kg04/vacuum/pssip_kg04.01/stat1[0] == 0);message=sip02_kg04.01 PS not ON

• eventSummary

  event=<attribute fqdn>;time=<date time s>;values=<attribute values>;exception=<attribute exception>;quality=<attribute quality>;
  Example:
  event=usa/vacuum/pssip_usa.22/stat1;time=2025-03-12 13:50:51;values=[1,1,0,1,1,0,0,0];exception=;quality=ATTR_VALID
  event=kg15/vacuum/pssip_kg15.01/stat1;time=2025-03-14 16:49:50;values=[];exception={"Reason":"Event_ERROR","Desc":"Tango error for kg15/vacuum/pssip_kg15.01/stat1: Not valid status","Origin":"kg15/vacuum/pssip_kg15.01/stat1"};quality=ATTR_INVALID;

Commands

Name	Input argument	Output argument	Description
Ack	DEVVAR_STRINGARRAY	DEV_VOID	Acknowledge the list of alarms passed as input argument
Load	DEV_STRING	DEV_VOID	Load a new alarm as a string of concatenated “key=value;”. Possible keys are those documented in the attribute properties. Note: The SearchAlarm command returns strings that have the correct syntax for the Load and Modify input arguments
Modify	DEV_STRING	DEV_VOID	Modify an existing alarm. Input argument has the same syntax of the Load command
Remove	DEV_STRING	DEV_VOID	Remove completely an alarm. Its configuration is deleted from the attribute properties
Enable	DEV_STRING	DEV_VOID	Enable an alarm whose name is passed as the input argument. It has to be in the OOSRV or SHLVD state. Enabled is set to 1 in the attribute properties
Disable	DEV_STRING	DEV_VOID	Disable an alarm whose name is passed as the input argument. Its state changes to OOSRV and enabled is set to 0 in the attribute properties. From OOSRV the alarm state can be changed only with the Enable command
Shelve	DEVVAR_STRINGARRAY	DEV_VOID	Shelve command disable temporarily the list of alarms passed as input argument. Only alarms which have a silent_time property > 0 can be shelved. Their state is changed to SHLVD for the period specified as silent_time or until the Enable command is called
Silence	DEVVAR_STRINGARRAY	DEV_VOID	Silence command disable temporarily the management of the audible condition of the list of alarms passed as input argument. Only alarms which have a silent_time property > 0 can be silenced. Their state continue to change following their normal behavior but they do not participate to the audibleAlarm evaluation for the period specified as silent_time or until the Enable command is called
SearchAlarm	DEV_STRING	DEVVAR_STRINGARRAY	Returns the list of configured alarms that match the name of the filter string. If the filter string is empty or *, the command returns the configuration of all alarms. The Alarm configuration is returned as a concatenated “key=value;” string, with the same syntax as the Load command
GetAlarmInfo	DEVVAR_STRINGARRAY	DEVVAR_STRINGARRAY	Returns the complete status of the alarm whose name is passed as input argument [0]. The return value is an array of strings “key=value;”. Other input arguments may specify keys to be included in the response. Format described below
ReLoadAll	DEV_VOID	DEV_VOID	Reaload the configuration of all alarms from attribute properties
ResetStatistics	DEV_VOID	DEV_VOID	Reset frequency counters
StopAudible	DEV_VOID	DEV_VOID	Reset audibleAlarm attribute
StopNew	DEV_VOID	DEV_VOID	Same as StopAudible, kept temporarily for compatibility with legacy alarm GUI

• GetAlarmInfo Returns the complete status of the alarm whose name is passed as the input argument. The return value is an array of strings “key=value;”. The keys are those described in the attribute properties plus:

  • value=one of the alarm state enum labels
  • attr_values=concatenation of “attrname=value;” of the last value of attributes evaluated in the formula
  • quality=the tango quality
  • exception=Reason:.. Desc:.. Origin:..
  • shelved=true/false
  • ack=ACK/NACK
  • audible=true/false
  • on_counter=how many times it evaluated consecutively true
  • on_counter=how many times it evaluated consecutively false
  • freq_counter=how many times is has been evaluated since last ResetStatistics
  • silent_time_remaining=how many minutes till when it will come back from shelved or silenced

  Example:

   [0]	 tag=ks_prealarm_sf6
   [1]	 state=NORM
   [2]	 message="Pre Alarm SF6 on modulator KS"
   [3]	 url=
   [4]	 formula=(ks/interlock/sf6_ks.01/StatSF6[1] == 0)
   [5]	 values={"ks/interlock/sf6_ks.01/statsf6[1]":1}
   [6]	 time=2025-02-09  07:33:19.411087
   [7]	 quality=ATTR_VALID
   [8]	 enabled=1
   [9]	 shelved=0
   [10]	 ack=1
   [11]	 audible=0
   [12]	 counter=2
   [13]	 freq_counter=7
   [14]	 on_delay=0
   [15]	 off_delay=0
   [16]	 priority=high
   [17]	 shlvd_time=-1
   [18]	 shlvd_end=-1
   [19]	 group=gr_ctrl|gr_linac
   [20]	 on_command=
   [21]	 off_command=
   [22]	 receivers=

Alarm states

Name	Value	Process condition	Alarm status	Acknowledge status	Description
NORM	0	NORMAL	Inactive	Acknowledged	Normal state
UNACK	1	ABNORMAL	Active	Unacknowledged	Alarm not acnowledged
ACKED	2	ABNORMAL	Active	Acknowledged	Alarm acknowledged
RTNUN	3	NORMAL	Inactive	Unacknowledged	Returned to normal not acnowledged
SHLVD	4	ANY	Any	Not applicable	Shelved: temporarily disabled with the Shelve command
DSUPR	5	ANY	Any	Not applicable	Suppressed by design: not possible to evaluate to alarm because of formula conditions. Note: it is not possible to enter in this state in this AlarmHandler implementation
OOSRV	6	ANY	Any	Not applicable	Out of service: manually disabled with the Disable command
ERROR	7	ANY	Any	Not applicable	Cannot be evaluated due to Tango or formula evaluation errors

Alarm Ecosystem

See Alarm Ecosystem for other projects related to AlarmHandlers and how they can be used together.