Integration with external systems¶

Integration with external systems uses PANIC built-in annunciation capabilities:

Fig. 13 Annunciation infrastructure¶

Mail¶

To enable PANIC to send emails, one needs to configure the following PyAlarm class properties:

MailMethod¶

It has to be set either to mail or smtp[:host[:port]].

If it is set to mail, PyAlarm devices will call os command mail to send emails. This option requires that all machines where PyAlarm device servers are running have mail available and properly configured (with sendmail or postfix, for example).

If it is set to smtp, PyAlarm devices will send emails with use of a specified (host, port) SMTP server.

FromAddress¶

This property specifies sender address that will appear as Sender in mail and SMS.

MailDashRoption¶

On some systems mail does not support default -S option. In that case, it is possible to require calling the mail with -r option to specify from address. One can do it by setting the MailDashRoption property value to the sender address.

If the property is empty or not defined, -r is not used.

SMS¶

Sending SMS is possible with the use of an external hardware gateway or service. It requires an smslib.Then the configuration is provided with the following properties:

SMSConfig: Arguments for sendSMS command (username and password ), formatted as the following

username:password,

SMSMaxLength: Maximum length of SMS messages,

SMSMaxPerDay: Maximum SMS messages per day,

smslib¶

To enable sending of SMSs there should be a custom smslib library installed on all machines where PyAlarm device servers are running. This library needs to be provided/developed by the site using PyAlarm. An example library is available here: https://github.com/S2Innovation/lib-s2i-smsdev

The library shall be a python package (or module) named smslib defining (and exposing) a class called SMSThread which inherits from threading.Thread.

The SMSThread shall have a constructor with the following signature:

def __init__(self, message='', dest='',  username='', password='', source=''):

, a PyAlarm is initalising an SMSThread object with the following:

message set to text to be sent,

dest set to list of phone numbers,

username and password paresed from the SMSConfig property,

source set according to the fromAddress property,

After the SMSThread object is initialised, the PyAlarm is starting the thread, so sending of SMSs shall be done def run(self): method.

Note

The SMS sending could also be done with an ACTION receiver with use of an SMS sending device server or command/program.

Also the smslib may use a tango device to send an SMS. See the following modules used at SOLARIS:

SOLARIS is using a Moxa GSM gateway, which provides an HTTP form to send SMSes.

A Text Talker¶

A text talker can be integrated with the use of an ACTION receiver.

Assuming that there is a text talker tango device alarm/notifications/talker with a command talk getting a text to speak as the argin, one can set up the following:

Phonebook entry:

%TALKER: ACTION(alarm:command,alarm/notifications/talker/talk, "There is an alarm " + $DESCRIPTION)

Then adding %TALKER to an alarm annunciators/receivers list or to the GlobalReceivers property, will make the talker speak a message when an alarm triggers.

eLog or other web-based systems¶

To send notifications or to create an entry in a web-based system, one can use a tango command ACTION with a tango device in the middle.

As the web applications may have a limit on the number of concurrent connections or entries, it is recommended to buffer/filter the entries in a device server to prevent flooding the app in case of many alarms are triggered.

PSI eLog integration example¶

In addition to server-side eLog daemon, PSI elog provides a command-line tool called elog, which enables adding eLog entries from a command-line. It uses a set of command-line arguments to specify host, port, username and password to determine how the eLog can be accessed as well as a logbook name, entry’s tags and content.

The elog command is used by an ELogSender tango device to send entries to eLog server.

elog -h <hostname> [-p port] [-d subdir]
                           Location where elogd is running
  -l logbook               Name of logbook
  -s                       Use SSL for communication
  [-v]                     For verbose output
  [-w password]            Write password defined on server
  [-u username password]   User name and password
  [-f <attachment>]        Up to 50 attachments
  -a <attribute>=<value>   Up to 50 attributes
  [-r <id>]                Reply to existing message
  [-q]                     Quote original text on reply
  [-e <id>]                Replace existing message
  [-x]                     Suppress email notification
  [-n 0|1|2]               Encoding: 0:ELcode,1:plain,2:HTML
  -m <textfile>] | <text>

More info is available at PSI eLog webpage

The ELogSender device has a command create_entry used by an ACTION annunciator to put an entry into a queue of entries to be sent to eLog. The queued entries are sent to the eLog at a constant interval. The queue size is limited to defined (i.e. 20) number of entries. If the queue is full, any new create_entry calls are discarded (a number of discarded entries are registered). This mechanism prevents the eLog server from overload in case of alarms’ flood (multiple alarms triggered in a short time).

A way how the entry is created from a create_entry argin is defined by ELogSender device properties. These properties provide matching between elements of argin (which is DevVarString) and eLog fields (called attributes).

An example configuration may look like the following:

ELogSender class properties:

ArgumentParsers: . (this privides addtional variables to be used in eleog message, experimental),
ELogAdditionalArgs: (this can be set to -u pylaram elog_password to provide pyalarm credentials to eLog),
ELogCommand: /usr/local/bin/elog (where to find the elog command),
ELogHost: localhost (a hostname or IP where the eLog server is running),
ELogPath: (an URL path of the eLog),
ELogPort: 8080 (a tcp prot of the eLog),
MaxQueueMessage: There is/are {%NumberOfRejectedEntries%} alarm(s) skipped to avoid flooding. {%n%} (this provides a way to include information about rejected entries in a logbook entry),
MaxQueueSize: 10 (entries que limit, if the que contains MaxQueueSize of entries, new one will be discarded, not sent to the eLog server),

alarm/ctl/elogsnd1 device properties:

EntryAttributes: Type={%3%},Category={%4%},Subject={%1%}-{%2%},Author=PyAlarm
EntryMessage: {%MaxQueueMessage%} {%0%}
LogbookName: demo

PANIC/PhoneBook free property entry: %LOGBOOK:ACTION(alarm:command,alarm/ctl/elogsnd1/create_entry,$REPORT,$NAME,$DESCRIPTION,'Routine','General')

PyAlarm/GlobalReceivers class property entry: *:piotr.goryl@s2innovation.com,%LOGBOOK

This will result in with entries looking as follows:

Fig. 14 An example eLog entry created from a PyAlarm¶

Knowledge database¶

A knowledge database link is configured with the AlarmWikiLink PyAlarm class property:

AlarmWikiLink: An URL to a WiKi page, where one can find more info on alarms. If set it will appear on the AlarmEditor widget. The URL may contain a key {%ALARM%} which is then substituted with an alarm tag. Example: http://wiki.cps.uj.edu.pl/alarms/{%ALARM%},