Rules

Pierre Kil edited this page Nov 15, 2016 · 11 revisions
Clone this wiki locally

After integrating devices and commands, you could add intelligence. Through adding Macros or Rules you can give the system the ability to perform a set of actions or even act without the users (direct) input. The more extensive way of describing behaviour can be done with Rules. This is very useful for time-based actions, such as switching on and off lights while on vacation; for activity-based actions reacting to the presence of people detected by sensors; or for a combination of those such as smart thermostats. The rules make use of the Drools language.

Switch to 'Building Modeler' view and on the bottom left choose the 'Controller Configuration' tab. From the list then select 'rules', as shown in Figure 1 below:

Rules - RuleConfigurationFinal
Figure 1: Enter Rule Definitions into Controller Configuration

Example Rule

A simple rule might look like shown in the listing below:

package org.openremote.controller.protocol

global org.openremote.controller.statuscache.CommandFacade execute;
global org.openremote.controller.statuscache.SwitchFacade switches;

rule "Turn Music On" when

  Event( source == "MySwitch", value == "on" )

then

  execute.command( "Music_On" );

end

A few notes on the rule definition above:

  • The package and global definitions are required as shown above for now (we may later omit them). They are necessary instructions for the rule compiler. Copy them as-is at the beginning of your rule definition. Do not change them.
  • The rule defines a descriptive name for your rule.
  • The when statement defines which sensor or sensors trigger your rule. The event source is your sensor's name (the name you've defined in your designer account for the sensor). The event value is the value the sensor must emit for the rule to be triggered -- values 'on' and 'off' are valid for 'switch' type sensors, integer values are valid for 'level' and 'range' type of sensors, and any arbitrary string is a valid value for a 'custom'-type sensor.
  • The then statement defines what should happen when the event conditions in the previous when statement are true. The execute statement triggers a command using a command name that you've defined in your designer account ('Music_On' in this case).

Command Execution Example

The example below shows the simplest command execution based on sensor value:

package org.openremote.controller.protocol

global org.openremote.controller.statuscache.CommandFacade execute;
global org.openremote.controller.statuscache.SwitchFacade switches;

rule "Execute Command" when

  Event( source == "trigger" )

then

  execute.command( "counter" );

end

The rule is executed whenever a 'trigger' sensor produces an event, regardless what the sensor value in the event is. In response, a controller command named 'counter' is executed by the controller. As in the previous example above, include the package and global statements as-is. The 'counter' command name is defined by you as your command name in the Designer, as is the 'trigger' as a sensor name producing events. The other rule elements are the same as in the basic command example shown earlier.

Timer Example

Rules can be executed based on timers. This example shows the most basic kind of timer definition:

package org.openremote.controller.protocol

global org.openremote.controller.statuscache.CommandFacade execute;
global org.openremote.controller.statuscache.SwitchFacade switches;

rule "Command Timer"

  timer (int: 0s 12h)

when eval(true)

then

  execute.command("Feed the Fish");

end

This rule is executed every 12 hours. The timer statement defines the interval of rule execution. It accepts two integer parameters: first one is the initial delay before the rule is triggered for the first time. The second parameter is optional with the repeat interval for the rule execution.

Initial delay and repeat interval can be defined in seconds, minutes or hours, using suffix 's', 'm' or 'h' respectively.

The when statement in this example is left empty with eval(true) statement which evaluates to true each time the timer triggers and therefore executes the command 'Feed the Fish' which you must define as a command name in the Designer. The rest of the rule language elements are explained in the examples above. You should copy the package and global statements as-is from this example.

See also