Alarm Protocol

MDAR edited this page Dec 1, 2016 · 12 revisions
Clone this wiki locally

This page describes the Alarm protocol which has been created within OpenRemote for the purpose of triggering one or more commands using a time trigger; this protocol provides time based events without the need for writing rules.

Version Compatibility

This protocol is available in Controller 1.5.0 onwards.

Alarm Definition

An Alarm is defined using the following information: -

Alarm Name: Unique name of the alarm

Cron Expression/Time Trigger: A cron expression defining the trigger time(s) for this alarm (the protocol uses the Quartz Scheduler to manage the alarms and the cron expression is any valid Quartz CRON Expression (see below)

Commands: A list of device names, command names and optional command parameter and delays (in milliseconds) to be executed when the alarm triggers (see below). The device and command names must match those used in the building modeller of the designer.

Enabled Status: A flag indicating if the alarm is currently enabled or not

Alarm Configuration File

Alarms are defined in the alarm configuration file which needs to be located within the following folder of the controller: -

.\webapps\controller\alarm\alarm-config.xml

The alarm config file must be created manually and must exist before you can display/edit alarms within your panels.

Example Configuration File

Below is an example config file that defines two alarms (Alarm1 and Alarm2) that are used to turn a pump and heater on/off: -

<?xml version="1.0" encoding="UTF-8"?>
<alarms>
<alarm name="Alarm2">
<cronExpression>0 32 19 ? * SUN,MON,TUE,WED,THU,FRI,SAT</cronExpression>
<commands>
<commandRef device="Device1" name="AlarmHeaterOff" delay="0" />
</commands>
<enabled>true</enabled>
</alarm>
<alarm name="Alarm1">
<cronExpression>0 31 19 ? * SUN,MON,TUE,WED,THU,FRI,SAT</cronExpression>
<commands>
<commandRef device="Device1" name="AlarmHeaterOn" delay="0" />
<commandRef device="Device1" name="ThermostatSet" parameter="20" delay="0" />
</commands>
<enabled>true</enabled>
</alarm>
</alarms>

Trigger Time

The CRON expression of the alarm as stated above determines the trigger date(s) and time(s) for the alarm; as the alarm protocol uses the Quartz Scheduler to manage the alarms any valid Cron trigger expression can be used in the alarm definition which allows the creation of very advanced alarm schedules (trigger every 5 minutes, trigger on first Monday of the month etc.).

When using the alarm protocol commands (see below) to change the active days and/or time of an alarm then these advanced CRON expressions are replaced with simple days of the week, hour and minute expressions e.g. "0 35 15 ? * SUN,MON,TUE,WED,THU,FRI,SAT"

It is possible to use advanced cron expressions and to persist these in the config file provided the only commands created for that alarm are to read/write the enabled status of the alarm.

For further reading refer to the Quartz Scheduler documentation: -

http://quartz-scheduler.org/documentation/quartz-2.x/tutorials/tutorial-lesson-06

Commands

The alarm commands are broken down into two types of command; read commands (for use by sensors) and write commands (for use by buttons, switches, etc.).

Command Definition

Commands are defined using the following properties: -

Alarm Name: Name of the alarm as defined in the alarm config file
Command: The command to use (drop down of options)
Value: Used for command parameters (depends on the command selected)

Read Commands

The following commands can be used to read the state of the alarms: -

Command: ENABLED_STATUS

Alarm Name: name of the alarm as defined in the alarm config file
Value: -
Returns: on/off
Description: Indicates if the specified alarm is enabled

Command: TIME_STATUS

Alarm Name: name of the alarm as defined in the alarm config file
Value: Offset Minutes in 25h format (optional e.g. 00:30 or 00:-15 or -01:-30 )
Returns: 24h based time as HH:MM
Description: Returns the trigger time for the specified alarm optionally offset by the specified number of minutes (the offset is useful for applications such as HVAC where the user is setting when they want the room to be warm/cool). For example an alarm called Alarm1 is used to trigger the heating to come on and it is displayed on the console with an offset of 00:30, using the console the user then sets the time to 16:00 (with +/- buttons) the actual alarm time is set to 15:30 which means the heating will be triggered on 30 minutes before the user requested.

Command: DAY_STATUS

Alarm Name: name of the alarm as defined in the alarm config file
Value: DAY (e.g. MON, TUE, WED, THU, FRI, SAT or SUN)
Returns: on/off
Description: Indicates if the specified alarm is enabled on the specified day

Write Commands

The following commands can be used to make changes to the alarms: -

Command: ENABLED

Alarm Name: name of the alarm as defined in the alarm config file
Value: TRUE or FALSE
Description: Enable or disable the specified alarm

Command: TIME

Alarm Name: name of the alarm as defined in the alarm config file
Value: HH:MM (24h based e.g. 00:30, 19:00)
Description: Set the trigger time for the specified alarm

Command: TIME_RELATIVE

Alarm Name: name of the alarm as defined in the alarm config file
Value: HH:MM (hours and mins to adjust by e.g. 00:-05 = Minus 5mins, 01:00 = Plus 1hr)
Description: Adjusts the trigger time by the specified amount for the specified alarm

Command: DAY

Alarm Name: name of the alarm as defined in the alarm config file
Value: DAY:STATUS (e.g. MON:TRUE or SUN:FALSE)
Description: Enables/Disables the alarm on the specified day