Item Rule Configuration

When editing Items, you have a "Rules" tab. This tab lists a number of pre-defined rules as shown below.

These rules are defined in a library file in XML format. The rule itself is defined, along with required imports, and variables required within the rules. When you click on the "Add Rule" button, HABmin presents a list of the variables for this rule which you can fill in. These are then replaced within the rule with the openHAB rule file is generated.

The "Delete Rule" button is available if the rule is already configured. Deleting a rule will only remove the rule and will not remove any Items that may have been produced when the rule was created.

When a rule is defined, the rule list is updated to show any linked items.

Any variables that aren't simply related to the setup of the rule will then be available in the Item Properties page.

Behind the scenes, HABmin saves all this configuration in a database (XML file if you want to look at it). It then generates the rules from this database. This means that if the rules library is updated, all copies of this rule can be updated easily.

HABmin will automatically generate a new item if required. This is done for any rules that have the special variable %%DerivedItem%%. HABmin will only create the base Item - it will not specify any groups, persistence or other attributes, but it will use the same format and icon as the original item. Currently, the new item is stored in a model file called "habmin.items". This could be changed to (for example) save the item into the same file as the original item.

Once a rule is saved, the variables used in its generation are available for editing in the item Properties tab. So, for example if you have a rule that updates a power item to display a lights power use in watts, and you change the lightbulb from 100W to 60W, all you need to do is change the number in the Item Properties and the rule will be updated.

The following rule template is defined in the library file. The filename is "rules_library.xml" and it's stored in the openhab directory. I may add a "rules_library_user.xml" at some stage as well if there's demand.

    <rule>
        <name>PowerConsumptionNow</name>
        <label>Calculate current power consumption</label>
        <type>DerivedItem</type>
        <itemtype>SwitchItem</itemtype>
        <itemtype>DimmerItem</itemtype>
        <description>Calculates the power consumed by the item given a user specified maximum power</description>
        <import>org.openhab.core.library.types.*</import>
        <import>org.openhab.model.script.actions.*</import>
        <trigger>Item %%ItemName%% changed</trigger>
        <action>var Number valState = %%ItemName%%.state as DecimalType</action>
        <action>var Number valWatts = valState * %%UserWatts%% / 100</action>
        <action>postUpdate(%%DerivedItem%%, valWatts)</action>
        <variable>
            <name>DerivedItem</name>
            <label>New Item Name</label>
            <type>Number</type>
            <value>%%ItemName%%_Watts</value>
            <description>The name of the new item.</description>
            <scope>Setup</scope>
        </variable>
        <variable>
            <name>UserWatts</name>
            <type>Number</type>
            <label>User defined Watts</label>
            <value>0</value>
            <description>Maximum power the item consumes when ON</description>
            <scope>Item</scope>
        </variable>
    </rule>

A description of the fields -:

• name This is the rule name. It MUST be unique as it's used to link everything together within the library
• label This is the label that the user will see in the HABmin interface
• itemtype (optional) If specified, this allows HABmin to display only rules that are applicable to particular item types. Multiple item types can be specified here. If not itemtype is specified, the rule will be available to all items.
• description Provides a slighty longer description of the rule.
• import Specifies imports that are required by the rule. These are consolidated by all rules and added to the start of the rule file.
• trigger Specifies the trigger conditions
• action Specifies the action to perform
• variable Lists variables that are used in the rule. HABmin will translate these when it writes the rules. Variable names can be anything you like, and when used in the rule (either other variable values, the action or trigger) should be surrounded by double percent signs (eg %%MyVariableName%%).

The following rule is created

// This rule file is autogenerated by HABmin.
// Any changes made manually to this file will be overwritten next time HABmin rules are saved.

import org.openhab.core.library.types.*
import org.openhab.core.persistence.*
import org.openhab.model.script.actions.*

// Calculates the power consumed by the item given a user specified maximum power
rule "DimmedLight: Calculate current power consumption"
when
  Item DimmedLight changed
then
  var Number valState = DimmedLight.state as DecimalType
  var Number valWatts = valState * 60
  postUpdate(DimmedLight_Watts, valWatts)
end