Merge branch 'improve_documentation' into 'master'

Improve documentation

See merge request !10

README.md

 # Alarm-handler
 Elettra alarm-handler Tango device
 
+## Documentation
+
+[Alarm-handler](docs/AlarmHandler.md)
 
 ## Building and Installation
 

docs/AlarmEcosystem.md

+# The Alarm Ecosystem
+
+There are several projects related to alarms, which can work together with AlarmHandlers.
+
+## AlarmNotify
+
+[alarm-notify](https://gitlab.elettra.eu/cs/ds/alarm-notify) connect to a list of alarm-handler devices and subscribes for the change event of their alarm attributes. It checks whether there are Recipients configured in individual alarms, or interested in alarms belonging to a group, or all alarms, then builds a list of recipients for each alarm state of each alarm.
+When an event is received, if there are recipients configured for the new alarm state, a command is triggered on a device for notification.
+A string parameter with a semicolon-separated list of “key=value” fields is passed to the notification command, with the following keys:
+```
+name=<_tag_>;handler=<AlarmHandler device>;values=<JSON attribute values>url=<_url_>;msg=<_msg_>;formula=<_formula_>;groups=<_groups_>;shlvd_time=<_shlvd_time_>;state=<Alarm state DevEnum label>;ack=<true|false>;time=<timestamp>;
+```
+
+See an example of configuration properties:
+
+![screenshot](images/alarm_notify_properties.png)
+
+## AlarmManager
+
+[alarm-manager](https://gitlab.elettra.eu/cs/ds/alarm-manager) is a Tango device server that supports the configuration of AlarmHandlers. AlarmHandlers are designed to be modular, so that different AlarmManagers can be configured to handle different groups/subsets of AlarmHandlers.
+AlarmManager can display the selected alarm configuration as attributes (_tag_, _formula_, _message_, _priority_, _group_, _shlvd_time_, _on_delay_, _off_delay_, _on_command_, _off_command_, _receivers_) or can Load/Modify alarms with the configuration provided in the attributes (_tag_, _formula_, _message_, ... same list as above)
+
+## AlarmMail
+
+[alarm-mail](https://gitlab.elettra.eu/cs/ds/alarm-mail) is a Tango device server  which exports commands able to send emails. Its commands can be configured in _on_command_ and _off_command_ properties (deprecated) or called by AlarmNotify.
+
+## AlarmHandlerGUI
+
+[alarm-handler-gui](https://gitlab.elettra.eu/cs/gui/alarm-ng) is the default AlarmHandler GUI at [Elettra](www.elettra.eu). It is designed to display different sets of AlarmHandlers. See:
+
+![screenshot](images/alarm_ng.png)
+
+The different lists of AlarmHandlers to use are taken from free properties. Same properties that can be used to configure AlarmManagers. See:
+
+![screenshot](images/free_properties.png)
+
+AlarmHandlerGUI is also able to display and search in alarm history stored by HDB++ (MySQL schema only). See:
+
+![screenshot](images/alarm_ng_history.png)
+
+## AlarmManagerGUI
+
+[alarm-manager-gui](https://gitlab.elettra.eu/cs/gui/alarm-manager) displays in a tree the list of alarms read from the AlarmManager's _alarmList_ attribute. When an alarm is selected in the tree, AlarmManager's _tag_ and _handler_ are written accordingly and all the other attributes contain the updated configuration, see:
+
+![screenshot](images/alarm_manager.png)
+
+This can then be modified or loaded as a new alarm if the _tag_ attribute has changed.
+
+## HDB++
+
+[EventSubscriber](https://gitlab.com/tango-controls/hdbpp/hdbpp-es) can be used to store alarm history: alarm are exported by the AlarmHandler interface as DevEnum attributes whose change and archive events are pushed in the code at any variation. The configuration of HDB++ is independent of the AlarmHandlers, but also AlarmManagerGUI can also do this.
+
+## PANIC
+
+[PANIC](https://gitlab.com/tango-controls/panic) is the Alarm System developed at [Alba](https://www.cells.es). Preliminary work has been done to support AlarmHandler as an alarm formula evaluation device for PANIC. Specifically, the _alarmSummary_ attribute, GetAlarmInfo command and alarm Devenum attributes are compatible between the two systems. PANIC should also be able of handle the configuation of AlarmHandlers in attribute properties, but the work has not yet been finalized.
+
+
+
+

docs/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, ... <br>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](https://gitlab.elettra.eu/cs/ds/alarm-notify) | No | "" |
+
+### Formula syntax
+
+See [Formula.md](./Formula.md).
+
+## Interface
+
+### Attributes
+
+#### Dynamic Attributes
+
+| Name | Attr. type | R/W type | Data type | Description |
+|------|:-----:|:-----:|:-----:|-----|
+| AlarmState | Scalar | READ |DEV_ENUM <br>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](./AlarmEcosystem.md) for other projects related to AlarmHandlers and how they can be used together.
\ No newline at end of file