Alarms Manager

This plugin provides an application for monitoring and configuring alarms reporting for installations comprising heterogeneous devices such as sensors, input/output devices, network devices and IP cameras, managed by several users possibly divided into groups. The application generates alarm logs and notifies users via e-mail, SMS text messages and/or Telegram messages.

This app works with any I/O Server providing datapoints representing input/output devices or sensors and can be used in combination with the GSM I/O Server, the SMTPSERVER I/O Server and the Telegram I/O Server to send notifications and receive commands and group messages.

Multiple GSM modems can be used to speed up delivery time of multiple messages and increase fault tolerance.

Before using the app, configure all the I/O Servers and cameras needed and make sure they all communicate correctly with HSYCO.

To view the Alarms Manager interface go to the URL of the "alarms2" project on your server; for instance https://192.168.0.50/hsycoserver/alarms2.
There are two additional interfaces for mobile devices, "alarms2small" and "alarms2small2", which offer the same functionalities except for the configuration section.

From the main page you can access the different sections:

Configuration

To access the configuration page click on the icon on the bottom-right corner of the main page.

This section is only available for HSYCO users holding admin rights.

All the devices defined in the configuration and set as "enabled" will be listed in the corresponding sections of the application with a specific view interface.

At the bottom of the configuration page you find a link to the Wiring Editor which gets automatically populated with the I/O devices defined in this application.

Following is the rest of the configuration sections:

Areas

Areas represent separate locations of the installation. Each area comprises different devices and users.

It is possible to create a hierarchical area structure by assigning parent areas to other areas. It is possible to create as many level as needed.

If more than one area is defined then, from the main page, it will be possible to select an area to filter the item listed in the various sections of the application.

I/O Devices

I/O Devices represent datapoints having a discrete set of possible values. The usual case is datapoints having a 1/0 value (corresponding to the ON/OFF states).

It is possible to define custom values by selecting the custom option in the value settings of a datapoint and listing its possible values separated by a comma (e.g. "1,2,3"). It is also possible to assign a user friendly label to each value appending it to the corresponding value after a ':' character (e.g. "1:OK,2:WARN,3:ERROR").

If the datapoint corresponds to a writable output and you want to allow users to change its value from the view interface select the Writable option

Sensors

As sensors you can add datapoints having "analog" values such as temperature, pressure and so on.

Configuration parameters:

• Unit: unit symbol used in the view interface for this sensor
• Min/Max: valid range for the sensor values. Values outside the specified range will be ignored by the application.
• Apply transformation: to be used in case a transformation is needed to calculate the actual measured value from the value of the specified datapoint. For instance, it can be used for temperature probes outputting a 4-20 mA value. The read value will be multiplied by the specified m value and then added to the t value.
• Create data logger: whether to create a data logger gathering data from this sensor. It will be visible in the sensor's view interface. It is possible to specify the persistence time of the saved data.

Pings

Here you can add network devices to monitor their connectivity (by means of "ping" requests sent from HSYCO). Specify their IP address or host name and set the device name.

It is possible to specify the interval at which ping requests are sent and the number of failures after which the device is considered unresponsive and thus an alarm is triggered.

Cameras

The cameras listed here are the ones defined in HSYCO's configuration. You cannot add or configure a camera from here.

As for the other sections, here you can enable/disable cameras to make them available or not in the view interface and assign them a descriptive name and the associated area.

Remotes

This section can be used to add remote Iono Pi devices or any programmable device able to send SMS messages configured to send data in the following format:

   <msg_id>;<digital_dp_1>=<val>;<analog_dp_1>#<val>;...<digital_dp_N>=<val>;<analog_dp_N>#<val>

Each message contains a list of datapoints with their corresponding value, separated by ';'. If a datapoint-value pair is separated by '=', then it is considered to be a digital (I/O) device, otherwise, if '#' is used, it is treated as a sensor (analog value). For each datapoint a corresponding variable is added to the I/O Devices or Sensors section, named "$REMOTE.<remote_id>.<dp_name>".

If a message ID is added at the beginning, an SMS acknowledge will be sent back to the remote device, containing the same ID. The message ID can be any string not containing ';'.

For each remote the variable "$REMOTE.<remote_id>.TIMEOUT" will also be added to the I/O Devices section. It's value will be set to '1' when no message is received from the device for a period longer than the one specified in the configuration.

General

• Delete log files after X days: specifies the persistence time of the log files created by the application
• E-Mail sender: the e-amail address to be used to send alarm notifications to users
• Max recording time on manual command: The cameras view interface gives the possibility to manually record images from the selected camera. This option specifies when to automatically stop the recording if not manually stopped
• Telegram registration command: The command to be used for user registration via Telegram, see the Users section.

Groups

A group represents a set of users monitoring the same set of devices.

Create/delete groups using the +/- buttons at the bottom of the list and enter a name.

For each group you can select the days it is active and, for each day, up to 2 time intervals in which it is active. When a group is active, the users belonging to the group will receive alarm notifications targeted for such group.

Groups currently active display a "•" symbol next to their names.

The Receives system alarms option specifies whether this group should receive system alarms triggered by the System I/O Server (which should be added in HSYCO's configuration) such as low storage available, no internet connectivity, disconnected I/O Servers and unreachable cameras.

Users

Create/delete users using the +/- buttons at the bottom of the list and enter a name.

• Enabled: whether or not this user is enabled, i.e. receives notifications.
• Group(s): select the group(s) the user belongs to
• E-Mail: if specified, alarms notifications for the user will be sent to the specified address
• Phone: if HSYCO is provided with a GSM I/O Server you can specify the phone number of the user that will be used to send SMS text notifications to. The user can send SMS messages to the GSM modem with body "on" or "off" to respectively enable or disable himself. Use the same number format described in the GSM I/O Server documentation
• Call after notification: select if a call should be placed to the user after sending an SMS notification. The call will be closed when rejected, answered or after a timeout.
• Telegram: if a Telegram I/O Server is configured, you can specify the Telegram user ID to be used. The user will also be able to send enable/disable commands as per SMS messages. If you don't know the Telegram user ID, see "Registration code"
• Registration code: if no Telegram ID is specified you can enable this option to automatically detect the user ID. The user can send a message to the configured Telegram Bot containing the registration command Specified in Configuration > General followed by the registration code, e.g. "/adduser 58928813". The user ID will be automatically filled
• Can send group messages: select if the user is allowed to send Group messages

I/O Devices

This section lists the configured I/O Devices. By selecting an entry you can view its current state and, if configured as writable, set its value.

For each device you can specify alarm conditions that will trigger notifications to the target groups. To add a condition click on the + icon:

The specified message (and subject for e-mails) will be sent via e-mail/SMS/Telegram to the users belonging to the target group (if active) when the specified condition evaluates to true.
You can have the app automatically add the name of the area the device belongs to and the time when the condition triggered.

• Notification delay: minimum persistence time for a condition to trigger the notifications, a value of zero means no delay
• Stop notifications after alarm for: to avoid repeated notifications you can specify a time interval after an alarm condition is exited in which new notifications will be suppressed, a value of zero means no notification is suppressed.

Devices for which alarm conditions have been defined show a "•" symbol next to their names in the list. If one of the conditions is active, both the condition and the device name turn red.

Sensors

This section lists the configured sensors. By selecting an entry you can view its current state and, if configured, its data logger chart.

As for I/O devices you can add alarm conditions:

Cameras

This page lists all the configured cameras. Click on a list entry to view the video stream of the camera and manually record frames.

For each camera you can create recording conditions associated to an I/O device switching to a specific value:

Ping

Here you can see all the monitored network devices and specify the target group(s) to send notifications to in case of loss of connectivity.

Log

This page lists all the recorded alarm events. You can select log entries and send them via e-mail in CSV format (clicking on the envelop icon) or delete them (clicking on the - icon).

Log entries are also stored in CSV files contained in the directory "alarms_manager_data/logs" in the HSYCO root on the server.

Group messages

Enabled users can send group messages via SMS (GSM I/O Server required), e-mail (SMTPSERVER I/O Server required), and Telegram (Telegram I/O Server required) to other users.

To send a group message via SMS, send a text to the connected GSM modem; to send it via Telegram, sent it to the configured Telegram Bot; to send it via e-mail, send it to the SMTP server addressing it to an e-mail address with the same username as the address from which notifications are sent. For instance, if notifications are sent from "alarms@hsyco.com", you can send the e-mail to any address like "alarms@<any_domain_name>".

The message sent must have the following format:

<area>:<group1>,<group2>,...,<groupN>#<message>

You can omit the area and/or the groups to send the message to all users without filtering by area/group.

Moreover, in case the message is sent from other devices which automatically add custom text, it is possible to add the delimiters "=>=" and "=<=" to respectively mark the beginning and the end of the portion of text that has to be processed. You can use both delimiters or just one of them.

For e-mails, the message can be sent both in the subject or in the body of the e-mail. Moreover, the area and groups can be specified alternatively in the e-mail address using the format:

<alarms_username>+<area>%<group1>#<group2>#...#<groupN>@<any_domain_name>

For instance:

alarms+area1%group1#group2@hsyco.com
alarms+group1#group2@hsyco.com
alarms+area1%@hsyco.com

Events

The application generates USER events that can be used to add custom logic to alarm events.

For each datapoint with alarm conditions defined, the following USER events are triggered:

alarm.<datapoint_id> = 1       // when at least an alarm condition on the datapoint is true
alarm.<datapoint_id> = 0       // when all alarm conditions on the datapoint are false

For each notification triggered, the following USER events are triggered:

alarm_notif.<datapoint_id> = message  // when a notification is triggered for the datapoint

Control variables

You can use the `$alrmsmngr2.disable.alarms` variable to enable/disable all notifications:

$alrmsmngr2.disable.alarms = 0  // notifications enabled
$alrmsmngr2.disable.alarms = 1  // notifications disabled

File Messages Extension

The File Messages Extension is an optional plugin that works in combination with the Alarms Manager plugin to provide file-based messages and an alternative alert routing logic for SMS alerts.

File Messages

Writing text files in a sub-directory named "alarms_manager_messages" will generate alerts to the appropriate SMS destination numbers, based on the current schedule defined in the Alarms Manager, or the alternative routing logic.

The messages sub-directory is also accessible, just like the main HSYCO directory, from remote systems as a shared HSYCO network disk server.

The plugin constantly scans the alarms_manager_messages for text files (files starting with ".", and the special-purpose "schedule.txt" file are ignored) having the following format:

<line1>
...
<lineN>
=end=

Note that files are ignored if the last line is different from the terminator text "=end=". This is intended to prevent the plugin from processing files that are not yet fully written by an external applicaton.

You can have multiple message lines in each file.

Each line can have a text message with no additional information, or a destination prefix with area and group(s) IDs:

<message>
#<message>
<group>#<message>
<group1>,<group2>,...<groupN>#<message>
<area>:<group1>,<group2>,...,<groupN>#<message>

The "#" character is the area/group prefix separator. If you want to have "#" characters in the message, always prepend the message with the "#", even if you don't need to set a group.

If the area or group are not set, the message is sent to all users associated with any group in the Alarms Manager plugin.

Text files are automatically deleted after processing.

message.txt example

This is an alert message to all users.
#This is an alert message to all users, with one or more ## characters in the text.
main_area: day, night#This is an alert message to users of groups day and night in area main_area

Alternative Alert Routing Logic

An alternative alert routing logic, overriding the current weekly schedule defined in the Alarms Manager, is based on a simple date-time interval match text file format, with associated list of recipients, defined with the "schedule.txt" file, located in the alarms_manager_messages directory:

<date-time-from>,<date-time-to>,<timeout>,<user1>,...,<userN>
*,*,*,<user1>,...,<userN>

The <user> fields in the file are the GSM numbers of Alarms Manager's active users. Numbers that are not associated with any user are ignored.

The date-time match is positive if the current time is: date-time-from <= current time < date-time-to. The date-time format can be any of the following, where the optional separator character can be a valid character, like "-", ".", " " or ":":

YYYYMMDDHHMM
YYYYMMDD-HHMM
YYYYMMDD-HH-MM
YYYY-MM-DD-HHMM
YYYY-MM-DD-HH-MM

When an alert message file is processed, each message will be sent to the users in the list matching the defined time interval. The plugin sends the message to the first user in the list, and an SMS reply to acknowledge alert’s reception is required within <timeout> seconds. If no acknowledge is received, the alert is sent to the next user in the list. Alerts that are not acknowledged by any user, or if all the user in the list are temporarily disabled, are sent (in parallel, no acknowledge required) to a jolly list.

The jolly list is a special list, defined in schedule.txt, as *,*,*,<user1>,...,<userN>.

An acknowledge is any text message -- except the "on" and "off" special messages, that are used to self-enable or disable a user.

schedule.txt example

20160101-00:00, 20160201-00:00, 30, 3331021340, 3285043097
201510061200, 20151007-12:00, 30, 29652932, 29652932, 29652931
2015-10-07-12:00, 20160101-12:00, 30, 29652937, 29652938, 29652939
*, *, *, 3489259249, 3306046740, 3109893094