Rules In OpenHAB

Rules Rule!

On this page

The Rules Engine

So far we've used OpenHAB to view sensor data, but for real home automation you need rules that use data to trigger actions.

OpenHAB comes with a powerful rules engine that unfortunately also has a bit of a learning curve. This page is intended as an introduction, where we set up a single action and rule as an example.

Online you'll find lots of examples of rules people have come up with, as well as resources for learning to make your own rules. Some of these resources are listed at the bottom of this page.

OpenHAB Designer

Rules are written in a Java-like language called XTend. You can write these rules in a simple text editor, but OpenHAB also comes with a free designer where you'll have features like syntax checking, color-coding, code validation and intelligent code completion.

Download the OpenHAB Designer for your platform (like Windows). It doesn't come with an installer so you just unzip it somewhere. Also make sure you followed the samba guide on this site so you have access to the OpenHAB folder on your Raspberry Pi.

When you start OpenHAB Designer, you need to first link it to your OpenHAB configurations folder. Click the "Open Folder" icon and browse to your OpenHAB folder, and then the configurations folder under that.

OpenHAB Designer
TIP: if you don't want to have to type your password every time you reboot your computer you can map the OpenHAB folder to a network drive.

Example Action: E-Mail

If you've been following this guide, you already have the email addon in the addons_repo folder. Copy the addon from addons_repo to addons (remember to replace 1.7.0 with the version you have):

sudo cp /opt/openhab/addons_repo/org.openhab.mail-1.7.0.jar /opt/openhab/addons/org.openhab.mail-1.7.0.jar

If you don't have the addons_repo folder, you can get the binding by downloading the addons zip from the OpenHAB downloads page.

Now instead of opening openhab.cfg in nano, you can open it in OpenHAB designer! Look for the section titled Mail Action configuration. If you have a GMail account, you'll need the settings below. If you have a different e-mail account you'll need to substitute your specific account settings.

mail:hostname=smtp.gmail.com
mail:port=587
mail:username=(your email address without the @gmail.com part)
mail:password=(your password; if you have two-way authentication, you need to generate an application-specific password)
mail:from=(your email address without the @gmail.com part)
mail:tls=true

Example Rule: Send Email When It Gets Hot

If you don't have a default.rules file yet (under the rules folder), you'll need to create it via MobaXTerm. OpenHAB Designer doesn't seem to have this functionality.

sudo touch /opt/openhab/configurations/rules/default.rules

Then you can open it in OpenHAB Designer. Now here's a rule I came up with to teach some basic concepts:

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

var Timer waitTimer = null
var boolean sentTemperature = false

rule "It's getting hot in here"
when
	Item TestTemperature changed
then
	logInfo("Temperature: ", TestTemperature.state.toString())
	if (!sentTemperature && TestTemperature.state > 75) {
		sendMail("<type your email address>", "It's warm", "Temperature reported by Arduino is " + TestTemperature.state)
		sentTemperature = true
		waitTimer = createTimer(now.plusMinutes(5))[|
			sentTemperature = false
		]
	}
end

  • At the top we import some standard libraries that will help with code validation & completion.
  • waitTimer and sentTemperature are two variables we'll use to prevent OpenHAB from spamming our email account (see below).
  • Each rule starts with the keyword rule followed by a name which you can choose freely.
  • The when part defines the trigger: in this case, we want to trigger the rule when the value of item TestTemperature changes.
  • The then part defines the action: the first line is to help with debugging: every time the temperature changes we write the value to the log (you can find the log in /logs/openhab.log).
  • The purpose of the sentTemperature boolean is to make sure the action isn't triggered too often. When the action is triggered first, we set it to true so the if part won't be entered again. Then we start a timer that will wait for 5 minutes and then reset sentTemperature to false. The result is that you won't get more than 1 e-mail every 5 minutes.
  • The other part of the if condition checks the temperature: TestTemperature.state > 75 means we'll only enter the next part when the temperature goes over 75 Fahrenheit.

To test the rule you can just breathe on your sensor a bit until the temperature goes above 75F. If all goes well, you'll receive an e-mail. If not, check the openhab log for clues.

Rule Success!

Learn More

Go Back

Guides