/Alarms ODB tree: Difference between revisions

From MidasWiki
Jump to navigation Jump to search
No edit summary
(The midas documentation has moved to https://midas.triumf.ca/docs/)
Tag: Replaced
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div style="column-count:4;-moz-column-count:4;-webkit-column-count:4">
The midas documentation has moved. See [https://midas.triumf.ca/docs/develop/reference/reference/odb_keys/#alarms /Alarms] on the ODB keys page and [https://midas.triumf.ca/docs/develop/features/monitoring_and_control/alarms/configuring/ Alarms: configuring] for the new documentation about the /Alarms ODB keys.
* [[Midas_documentation|Midas Documentation]]
* [[Feature_listing|Feature Listing]]
* [[Application_listing|Application Listing]]
* [[Online_Database|Online Database]]
</div>
 
 
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Alarms Page]]
* [[Alarm System]]
* [[Mhttpd|mhttpd MIDAS web server]]
* [[odbedit]]
</div>
= Purpose =
The ODB /Alarms tree contains user and system information related to alarms (see [[Alarm System]]).
 
= Creating the /Alarms tree =
When the ODB is created, the /Alarms tree is automatically created, with
* two Alarms with  [[#<alarm-name> subtree|<alarm name>]] "Demo ODB" and "Demo periodic" and
* two Classes with [[#<class-name> subtree|<class name>]] "Alarm" and "Warning".
 
These are shown in the [[#Example of an /Alarms tree|example below]].
 
The user may create other alarms and classes by copying an existing <alarm-name> or <alarm-class> subtree and editing as required.
 
By default, the [[Alarm System]] is NOT active
Currently, the overall alarm is checked once every minute. Once the alarm has been triggered, the message associated with the alarm can be repeated at a different rate.  
 
 
= Examples =
== Default /Alarms tree ==
 
This /Alarms tree is shown using [[odbedit]] (see also mhttpd Alarm page).
 
$ odbedit
[local:pol:S]/>cd /alarms
[local:pol:S]/Alarms>ls
Alarm system active            y
Alarms
Classes
 
[local:pol:S]/Alarms>ls -r -lt
Key name                        Type    #Val  Size  Last Opn Mode Value
---------------------------------------------------------------------------
Alarms                          DIR
    Alarm system active        BOOL    1    4    4h  0  RWD  y
    Alarms                      DIR
        Demo ODB                DIR
            Active              BOOL    1    4    >99d 0  RWD  n
            Triggered          INT    1    4    >99d 0  RWD  0
            Type                INT    1    4    >99d 0  RWD  3
            Check interval      INT    1    4    >99d 0  RWD  60
            Checked last        DWORD  1    4    >99d 0  RWD  0
            Time triggered firstSTRING  1    32    >99d 0  RWD
            Time triggered last STRING  1    32    >99d 0  RWD
            Condition          STRING  1    256  >99d 0  RWD  /Runinfo/Run number > 100
            Alarm Class        STRING  1    32    >99d 0  RWD  Alarm
            Alarm Message      STRING  1    80    >99d 0  RWD  Run number became too large
        Demo periodic          DIR
              Active              BOOL    1    4    >99d 0  RWD  n
            Triggered          INT    1    4    >99d 0  RWD  0
            Type                INT    1    4    >99d 0  RWD  4
            Check interval      INT    1    4    >99d 0  RWD  28800
            Checked last        DWORD  1    4    >99d 0  RWD  1058817867
            Time triggered firstSTRING  1    32    >99d 0  RWD
            Time triggered last STRING  1    32    >99d 0  RWD
            Condition          STRING  1    256  >99d 0  RWD
            Alarm Class        STRING  1    32    >99d 0  RWD  Warning
            Alarm Message      STRING  1    80    >99d 0  RWD  Please do your shift checks
      fePOL                  DIR
            Active              BOOL    1    4    19s  0  RWD  y
            Triggered          INT    1    4    19s  0  RWD  205
            Type                INT    1    4    3s  0  RWD  2
            Check interval      INT    1    4    19s  0  RWD  60
            Checked last        DWORD  1    4    19s  0  RWD  1259196026
            Time triggered firstSTRING  1    32    19s  0  RWD  Wed Nov 25 12:59:33 2009
            Time triggered last STRING  1    32    19s  0  RWD  Wed Nov 25 16:40:26 2009
            Condition          STRING  1    256  3s  0  RWD  Program not running
            Alarm Class        STRING  1    32    19s  0  RWD  Caution
            Alarm Message      STRING  1    80    19s  0  RWD  Program fePOL is not running
  Classes                      DIR
        Alarm                  DIR
            Write system messageBOOL    1    4    27h  0  RWD  y
            Write Elog message  BOOL    1    4    27h  0  RWD  n
            System message interINT    1    4    27h  0  RWD  60
            System message last DWORD  1    4    27h  0  RWD  0
            Execute command    STRING  1    256  27h  0  RWD
            Execute interval    INT    1    4    27h  0  RWD  0
            Execute last        DWORD  1    4    27h  0  RWD  0
            Stop run            BOOL    1    4    27h  0  RWD  n
            Display BGColor    STRING  1    32    27h  0  RWD  red
            Display FGColor    STRING  1    32    27h  0  RWD  black
        Warning                DIR
            Write system messageBOOL    1    4    >99d 0  RWD  y
            Write Elog message  BOOL    1    4    >99d 0  RWD  n
            System message interINT    1    4    >99d 0  RWD  60
            System message last DWORD  1    4    >99d 0  RWD  0
            Execute command    STRING  1    256  >99d 0  RWD
            Execute interval    INT    1    4    >99d 0  RWD  0
            Execute last        DWORD  1    4    >99d 0  RWD  0
            Stop run            BOOL    1    4    >99d 0  RWD  n
            Display BGColor    STRING  1    32    >99d 0  RWD  red
            Display FGColor    STRING  1    32    >99d 0  RWD  black
 
 
 
 
== Alarm triggering Email or SMS alerts ==
 
It is also possible to have the MIDAS alarm system send email or SMS alerts to cell phones when alarms are triggered. This can be configured by defining an ODB alarm on a critical ODB parameter, e.g.
 
/Alarms/Alarms/Liquid Level
Active                  y
Triggered                0 (0x0)
Type                    3 (0x3)
Check interval          60 (0x3C)
Checked last    1227690148 (0x492D10A4)
Time triggered first    (empty)
Time triggered last    (empty)
Condition              /Equipment/Environment/Variables/Input[0] < 10
Alarm Class            Level Alarm
Alarm Message          Liquid Level is only %s
 
In this example, the alarm triggers an alarm of class "Level Alarm". This alarm class is defined as follows:
 
/Alarms/Classes/Level Alarm
Write system message    y
Write Elog message      n
System message interval 600 (0x258)
System message last    0 (0x0)
Execute command        /home/midas/level_alarm '%s'
Execute interval        1800 (0x708)
Execute last            0 (0x0)
Stop run                n
Display BGColor        red
Display FGColor        black
 
The key here is to call a script "level_alarm", which can send emails. Use something like:
 
#/bin/csh
echo $1 | mail -s \"Level Alarm\" your.name@domain.edu
odbedit -c 'msg 2 level_alarm \"Alarm was sent to your.name@domain.edu\"'
 
The second command just generates a MIDAS system message for confirmation. Most cell phones (depends on the provider) have an email address. If you send an email there, it will be translated into a SMS message.
 
The script file above can of course be more complicated. A perl script could be used that parses an address list, so other interested parties can register by adding his/her email address to that list. The script may also collects some other slow control variables (like pressure, temperature) and combine them into the SMS message.
 
For very sensitive systems, having an alarm via SMS may not be sufficient, since the alarm system could be down (e.g. computer crash, network failure). In this case 'negative alarms' can be used. For example, every 30 minutes the system may send an SMS with the current parameter values. If the expected message is not received, it may indicate that something in the MIDAS system is wrong.
 
 
 
<div id="Alarm class"></div>
= /Alarms tree structure =
The Alarms structure is split into 2 sections:
*"Alarms" which define the condition to be tested. The user can create as many Alarms as desired, but each must be one of the four defined Alarm Types .
*"Classes" which define the action to be taken when the alarm occurs. Two Classes (Alarm and Warning) are defined by default. The user can add more [[#Classes subtree|Classes]] as desired.
<br><br>
 
In order to make the system flexible, each alarm class may perform different actions when an alarm is given. For example, it may
* write a system message (see [[#Write System Message|Write System Message]])
* write to the elog (see [[#Write Elog Message|Write Elog Message]])
* stop the run (see [[#Stop run|Stop run]])
* spawn a detached script listed in the ODB variable [[#Execute command|Execute command]]. This feature is used when an Alarm triggers Email or SMS alerts (see [[#Alarm triggering Email or SMS alerts|example]]).
<br>
'''<div id="Alarm Type"></div>'''
 
The four available Alarm Types are shown in Table 1. They are defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-old/html/midas_8h.html&nbsp midas.h]. The alarm type is entered into the [[/Alarms ODB tree#Type|Type]] key.
 
 
{|  style="text-align: left; width: 100%; background-color: white;" border="3" cellpadding="2" cellspacing="2"
|+ Table 1 : Defined Alarm Types
|-
| colspan="2" rowspan="1" style="vertical-align: top; background-color: lavender; font-weight: bold;" | Alarm Type
| colspan="1" rowspan="1" style="vertical-align: top; background-color: lavender; font-weight: bold;" | INT value
| colspan="1" rowspan="1" style="vertical-align: top; background-color: lavender; font-weight: bold;" | Explanation
 
|- 
| colspan="1" rowspan="1"  style="vertical-align: top; background-color: white; font-weight: bold;"  |Internal alarms
| colspan="1" rowspan="1"  style="vertical-align: top; background-color: white; font-weight: normal;" | AT_INTERNAL
|1
|Trigger on internal (program) alarm setting through the use of the al_...() functions.
 
|- 
| style="vertical-align: top; background-color: white; font-weight: bold;" |Program alarms
|AT_PROGRAM
|2
|Triggered on condition of the state of the defined task.
 
|- 
| style="vertical-align: top; background-color: white; font-weight: bold;" |Evaluated alarms
|AT_EVALUATED
|3
|Triggered by ODB value on given arithmetical condition.
 
|- 
| style="vertical-align: top; background-color: white; font-weight: bold;" |Periodic alarms
|AT_PERIODIC
|4
|Triggered by timeout condition defined in the alarm setting.
 
|}
 
 
== Program Alarm ==
The Program Alarms are enabled for individual programs by setting [[/Programs ODB tree#Alarm class|Alarm class]] in the ODB <span style="color: purple; font-style:italic;">/Programs/<program></span> subtree. See [[Alarm System]]
for details.
 
== Periodic Alarm ==
The periodic alarm is activated periodically according to the time in [[#Check interval|Check interval]]. An example of a periodic alarm is "Demp Periodic" in the  [[#Default /Alarms tree|example above]].
 
== Evaluated Alarm conditions ==
 
The alarm condition for evaluated alarms is entered into the ODB key [[#Condition|Condition]] in the  [[#<alarm_name> subtree|<alarm_name> subtree]].
The condition may be simply a '''comparison''' between any ODB variable and a threshold parameter, e.g.
 
/Runinfo/Run number > 100
or it may be an '''evaluated condition'''. One can write conditions like
 
  /Equipment/HV/Variables/Input[*] < 100
or
 
  /Equipment/HV/Variables/Input[2-3] < 100
to check all values from an array or a certain range. If one array element fulfills the alarm condition, the alarm is triggerrd. In addition, bit-wise alarm conditions are possible, e.g.
 
  /Equipment/Environment/Variables/Input[0] & 8
The alarm is triggered if bit #2 is set in Input[0].
 
== Internal Alarms ==
These are triggered in a program using a call to
[http://ladd00.triumf.ca/~daqweb/doc/midas/doc/html/group__alfunctioncode.html#gac024cd8160dc8b9418f05a63678f6c68&nbsp al_trigger_alarm()]. See also [[Alarm System#Implementation of the MIDAS Alarm System|Alarm System]].
 
= Keys in the  <span  style="color: purple;">''/Alarms''</span> ODB tree  =
 
==  <span  style="color: purple;">''Alarm system active''</span>  ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:'''  "n"
</div>
 
If this key in the [[#top|/Alarms ODB tree]]
is set to "y", the alarm system is active. Set to "n" to deactivate.
 
 
<br>
---------
<br>
 
==  <span  style="color: purple;">''Alarms''</span> subtree  ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
 
 
 
Sub-tree in the [[#top|/Alarms ODB tree]] defining each individual alarm condition.
 
 
<br>
---------
<br>
 
 
===  <span  style="color: purple;">''<alarm-name>''</span> subtree  ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
 
 
This subtree in the [[#Alarms subtree|/Alarms/alarms subtree]] specifies the ''name'' of one of the defined alarms, where ''name'' is substituted for  <alarm-name>.  This subtree will be repeated with a different name for each defined alarm.
In the [[#Example|example]] two ''<alarm-name>'' subtrees are shown, called "''demo odb''" and  "''demo periodic''"
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Active''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:'''  "n"
</div>
 
If this key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is set to "y" , this particular alarm is active.
 
 
 
 
<br>
---------
<br>
 
 
===  <span  style="color: purple;">''Triggered''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:'''  0
</div>
 
If this key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is non-zero, this alarm has been triggered. Filled by System.
 
 
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Type''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 
</div>
 
This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] must be one of the listed [[#Alarm Type|Alarm Types]].
 
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Check interval''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:'''  60
</div>
 
 
This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] contains the
frequency in seconds at which this alarm condition is to be checked by the alarm system.
 
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Checked last''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 
</div>
 
 
This key in the [[#<alarm-name> subtree|<alarm-name> subtree]]  is written by the Alarm System.
 
 
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Time triggered first''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' 
</div>
 
 
This key in the [[#<alarm-name> subtree|<alarm-name> subtree]]  is written by the Alarm System.
 
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Time triggered last''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' 
</div>
 
 
This key in the [[#<alarm-name> subtree|<alarm-name> subtree]]  is written by the Alarm System.
 
 
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Condition''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' 
</div>
 
 
This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] contains
the condition on which alarm should trigger for [[#/Alarms tree structure|evaluated alarms]]. See [[#Evaluated Alarm conditions]].
 
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Alarm class''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' 
</div>
 
 
This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is set to one of the existing Alarm classes, e.g. "Alarm","Warning".
The Alarm class must be defined in the [[#<class-name> subtree|Classes subtree]].
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Alarm message''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' 
</div>
 
This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] constains
the message to be written when alarm triggers.
 
 
 
<br>
---------
<br>
 
 
==  <span  style="color: purple;">''Classes''</span> subtree ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
 
Sub-tree in the /Alarms ODB tree defining each individual alarm class.
Each class defines the individual action to be performed by a predefined and requested alarm.
 
<br>
---------
<br>
 
 
 
===  <span  style="color: purple;">''<class-name>''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
 
This subtree in the [[#Classes subtree]] defines one of the alarm classes of name ''name'', where ''name'' is substituted for <class-name>. This subtree will be repeated with a different name for each defined class. In the [[#Example of an /Alarms tree|example above]], two <class-name> subtrees are shown, named "Alarm" and "Warning". 
 
 
<br>
---------
<br>
 
 
 
====  <span  style="color: purple;">''Write System Message''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:'''  "y"
</div>
 
 
If this key in the [[#<class-name> subtree|<class-name> subtree]] is set to "y", a message will be sent to the [[System log]] when an alarm with this [[#Alarm class|alarm class]] is triggered.
 
<br>
---------
<br>
 
 
 
====  <span  style="color: purple;">''Write Elog Message''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:'''  "n"
</div>
 
 
 
If this key in the [[#<class-name> subtree|<class-name> subtree]] is
set to "y", a message will be written to the Elog when an alarm with this  [[#Alarm class|alarm class]] is triggered.
 
 
 
 
<br>
---------
<br>
 
 
 
====  <span  style="color: purple;">''System message interval''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:'''  60
</div>
This key in the [[#<class-name> subtree|<class-name> subtree]] contains the
interval in seconds between successive system messages when an alarm with this  [[#Alarm class|alarm class]] is triggered
 
See also [[Alarm System#Implementation of the MIDAS Alarm System]] for note on the implementation of this key by the alarm system.
 
<br>
---------
<br>
 
====  <span  style="color: purple;">''System message last''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:'''  0
</div>
 
This key in the [[#<class-name> subtree|<class-name> subtree]] contains the time when the last alarm system
message was written. It is filled by the alarm system.
 
 
<br>
---------
<br>
 
 
 
====  <span  style="color: purple;">''Execute command''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''  ""
</div>
 
This key in the [[#<class-name> subtree|<class-name> subtree]] may contain a
command to be executed when an alarm with this  [[#Alarm class|alarm class]] is triggered.
This parameter can be used to trigger [[#Alarm triggers Email or SMS|Email or SMS]] alerts.
 
 
 
<br>
---------
<br>
 
 
====  <span  style="color: purple;">''Execute interval''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:'''  0
</div>
 
When an alarm with this  [[#Alarm class|alarm class]] is triggered, if a valid
[[#Execute command|Execute command]] is supplied, the command will be repeated at an interval in seconds designated by this key in the [[#<class-name> subtree|<class-name> subtree]], providing the interval set is greater than 0.
 
 
 
 
<br>
---------
<br>
 
====  <span  style="color: purple;">''Execute last''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:'''  0
</div>
 
This key in the [[#<class-name> subtree|<class-name> subtree]]
contains the time when the alarm system last executed the command in the key [[#Execute command|Execute command]].
It is filled by the alarm system.
 
 
<br>
---------
<br>
 
 
 
====  <span  style="color: purple;">''Stop run''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:'''  "n"
</div>
 
This key in the [[#<class-name> subtree|<class-name> subtree]]  if set to "y"
will cause the run to stop when an alarm with this [[#Alarm class|alarm class]] is triggered.
 
 
<br>
---------
<br>
 
 
 
====  <span  style="color: purple;">''Display BGColor''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''  "red"
</div>
 
This key in the [[#<class-name> subtree|<class-name> subtree]] contains the
background colour of the alarm banner on the [[mhttpd]]  [[Status Page]]. The alarm banner
appears if the alarm is triggered.
 
 
 
<br>
---------
<br>
 
 
 
====  <span  style="color: purple;">''Display FGColor''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''  "black"
</div>
 
This key in the [[#<class-name> subtree|<class-name> subtree]] contains the
foreground colour of the alarm banner on the [[mhttpd]] [[Status Page]].  The alarm banner
appears if the alarm is triggered.
 
[[Category:ODB Tree]]
[[Category:Alarms]]

Latest revision as of 22:00, 30 October 2026

The midas documentation has moved. See /Alarms on the ODB keys page and Alarms: configuring for the new documentation about the /Alarms ODB keys.