# OI Alarm System
OI provides an alarm system which can monitor tag values and display alarm messages.
Note
This feature is available in OI versions 1.11 and newer.
# Operation
The OI alarm system monitors a series of tags and triggers an alarm. Alarms in OI have 2 effects:
- the alarm is logged into an internal database
- the alarm overlay is displayed on the screen
Prebuilt alarm screens for history and debugging the alarm system are created when the alarm system is enabled. These screens should be modified as needed. The alarm system is configured through a CSV file that contains the tag-alarm mapping.
Communication adapters are added for the tags needed in the pre-built screens. These tags cannot be modified, but they can be used elsewhere in your application.
When an alarm is triggered, an entry is added to the alarm history database. If the alarm condition goes away, the alarm will remain displayed until it is cleared.
Alarms are kept in the database until they are removed. The alarm system can be configured to automatically remove alarms when they are cleared as well.
The alarm history database should persist between reboots. The database can be forced to be rebuilt by resetting the database.
Clearing, removing, and resetting the database are triggered by writing a 1 to the oialarms_clearAll, oialarms_removeAll, and oialarms_resetDB tags. These can be controlled by the PLC by using a tag-copy to copy the values to internal tags.
# Alarm trigger
Alarms are triggered when a tag defined in the tag-alarm map goes from zero to 1 (or in the case of alarms by number, when the tag changes to that number).
# Alarm database
Alarms are stored in an internal database. The alarm time, triggering tag, triggering bit, triggering number, alarmtext, when the alarm was triggered, and when the alarm was cleared are stored.
Note
The alarm database is stored in an SQLite file located at /tmp/db/sqlite/oialarms.sqlite
# Clear Alarms
Clearing alarms sets the "clearedon" column to the current timestamp. This acts as an acknowledgement that the alarm has been seen.
Cleared alarms will remain in the alarm history database unless the auto-delete setting is enabled in OIB (Application Settings -> Alarms).
# Remove Alarms
Removing alarms removes alarms from the alarm history database. Any tags that are still in alarm condition will trigger new alarms to be added.
# Reset Alarm Database
This rebuilds the alarm database file. This may be useful for debugging or if the alarm file is corrupted.
# Configuration
# Enabling Alarm System
The alarm system is enabled and configured in OIB by going to the Application->Settings->Alarms dialog.
# Alarm Map CSV File
Example Alarm CSV file shown in a spreadsheet program
OI uses a CSV file to allow programmers and maintenance to build, deploy, and maintain alarm maps separately from OI itself. The intent was to allow the use of Excel or other spreadsheet tools to facilitate the creation and management of large lists of alarms.
# Format Requirements
The CSV file contains a map between tags and alarms.
Lines starting with # will be ignored.
Empty lines are ignored.
Tags must be an ordinal type, such as Int, UInt, Bit, Bcd4, BitArray.
The bit# is either the index of the bit (zero indexed), or a number value for the tag. If using number values for triggering alarms, prepend the number with '#'.
# CSV Example
Example csv file registering alarms for bit_alarms and num_alarms tags:
# Tag , Bit#/Number , Message
bit_alarms , 0 , Bit Alarm (bit 0)
bit_alarms , 1 , Bit Alarm (bit 1)
bit_alarms , 2 , Bit Alarm (bit 2)
bit_alarms , 3 , Bit Alarm (bit 3)
num_alarms , #1 , Numeric Alarm (number 1)
num_alarms , #2 , Numeric Alarm (number 2)
num_alarms , #3 , Numeric Alarm (number 3)
num_alarms , #4 , Numeric Alarm (number 4)
# OIB CSV Check
Two examples of CSV Checks - unsuccessful and successful.
You can use OIB to verify that the CSV file will be read.
# Alarms by Bit
Alarms defined by bit are triggered when the bit value goes from 0 to 1. These are defined in the CSV file like this:
alarm_bit_000, 0, Alarm Bit 0 of 000
alarm_bit_001, 0, Alarm Bit 0 of 001
alarm_bit_000, 1, Alarm Bit 1 of 000
alarm_bit_001, 1, Alarm Bit 1 of 001
This would create 4 alarms watching values of 2 tags. If the tags are defined as bit data types, the alarms using bit 1 will never trigger.
Using bit location can help reduce communication traffic and consequently speed up some applications. Instead of having 16 individual tags, we can use a data type (like UInt, BitA, or others) that represents many bits in one tag.
# Alarms by Number
Alarms defined by number are triggered when the tag equals the number defined in the CSV file. These are defined in the CSV file like this:
alarm_num, #0, Alarm number 0 triggered
alarm_num, #1, Alarm number 1 triggered
alarm_num, #2, Alarm number 2 triggered
WARNING
Setting the alarm number to zero will trigger an alarm when the tag evaluates to zero. In this example, when the tag is set to value 0 an alarm will be triggered. This can be unexpected.
# Alarm Screens
OIB Generates 3 alarm screens: Alarm Overlay, Alarm History, and Alarm Maintenance. These screens are grouped separately from others and can be modified.
Alarm screens use OI's Dynamic Panels functionality. See the Dynamic Panels Manual for more information.
TIP
If you change the resolution of your application, you can use the "Reset Alarm Screens" button in the Alarm configuration dialog to rebuild the alarm screens for a better fit to the new resolution. You can also manually adjust the elements as you need.
# Alarm Overlay
Alarm overlay template shown at the top of an application.
The alarm overlay will appear whenever uncleared alarms exist. You can modify the overlay to add a button to clear the alarms directly, to display other information, or to resize the elements as needed.
# Alarm History
Alarm history template showing recent alarms.
The alarm history screen shows a history of alarms. From here the alarms can be cleared/acknowledged.
Included in the standard template is a button to navigate to the Alarm Maintenance screen. You will likely want to remove or password protect this button before deploying your application.
# Alarm Maintenance
Alarm maintenance template
The alarm maintenance screen provides a few tools to help test and debug the alarm system. It provides buttons for 2 test alarms to ensure the database functions. It also provides a view of uncleared alarms and of all alarms. Finally, the screen provides buttons to clear alarms, remove alarms, and reset the database.