WTF Rules? in OH 2.1

Hi @ All
I’m running OH 2.1 on a Intel NUC with headless debian installation… maybe I’ve overlooked something, but can’t find an actual documentation of creating rules in .rules files for OH 2.1. I’ve tried to figure out which syntax is used for these files but with no luck so far.
I’ve seen many rule solutions here in the forum but they differ a lot, and I’m trying to find out which way rules are written for openhab 2.
e.g. do I use
item ItemName changed from XX to XX
ItemName changed from XX to XX
ItemName.state changed from XX to XX

I think I’m going slightly mad with it…
please, where can one find an actual description?? I wonder if there’s nothing like this online??

P.S please dont point me to the rules documentation, because it’s not completed yet and don’t gives any further explanation of rule syntax.

thanks in advance


Sry, had to edit the post 'cause it has not shown up… now it’s updated correctly! maybe an error with the page??

Docs definitely can be frustrating and confusing but it does specifically outline event-based triggers as:

Item <item> received command [<command>]
Item <item> received update [<state>]
Item <item> changed [from <state>] [to <state>]

This translates to your first example: Item ItemName changed from XX to XX

Sample rule:

rule Test
     Item TestItem changed from OFF to ON
     logInfo("Test rule", "TestItem has changed from OFF to ON")

thanks a lot @Moxified … will try that!
aren’t there any syntax explanations what I can or can’t do with rules, and is a defined language used for the syntax, so that I can read a little about how it works? I think ‘trial & error’ is not my preferred way of programming because it’s so timewasting and frustrating with only a small amount of satisfaction over all.

I saw some of you guys used external classes in their rules, where do this classes belong to/come from? Another question is I use VS Code as editor/IDE is that Ok, or is it even better to use the Eclipse SmartHome-Designer plug?

Well, I guess I see your point on lack of examples. I learned OH rules in 1.x which had a different set of documents. The rules syntax is virtually identical as far as I know. As such, I tend to use my own rules as starting points for new rules. I’m an SE not a code monkey so each time I touch this stuff I have to remember and my rules are pretty plain. I don’t think in classes and arrays etc.

That being said, there are some sample rules in the 1.x documents that might help here:

Edit: Mind the imports. OH2 doesn’t need most of the imports those sample rules have.

As for the IDE, no idea. I use the ESD because it is what they recommend and I avoid visual studio because M$ is evil :smiley:

The same as they were written in OH 1.x. It is the same Rules engine.

Then please explain where they are insufficient so we can fix them. This isn’t a rhetorical request. We really need and want to know specifically where people find problems with the docs so we can make them better. Blanket “they all suck” is not helpful though. We need actionalble recommendations and specific problems.

For instance, your specific question:

is answered in the Rules docs:

The Rules section contains a list of rules. Each rule has the following syntax:

rule "rule name"

Event-based Triggers
You can listen to commands for a specific item, on status updates or on status changes (an update might leave the status unchanged). You can decide whether you want to catch only a specific command/status or any. Here is the syntax for all these cases (parts in square brackets are optional):

Item <item> received command [<command>]
Item <item> received update [<state>]
Item <item> changed [from <state>] [to <state>]

As far as I’m aware it is complete. What is missing?

Further explanation of rule syntax is also available (and linked to from the Rules doc) at

Also answered in the Rules docs:

The Imports section contains import statement just like in Java. As in Java, they make the imported types available without having to use the fully qualified name for them. For further details, please see the Xtend documentation for imports.

And the Xtend documentation in that link (the original has a link) says:

The ordinary imports of type names are equivalent to the imports known from Java. Again one can escape any names conflicting with keywords using a ^. In contrast to Java, the terminating semicolon is optional. Non-static wildcard type imports are deprecated for the benefit of better usability and well defined dependencies.

Xtend also features static imports for importing static fields and methods. The semantics and syntax are just like in Java.

As in Java all classes from the java.lang package are implicitly imported.

And in the Java Interop section it says:

Resembling and supporting every aspect of Java’s type system ensures that there is no impedance mismatch between Java and Xtend. This means that Xtend and Java are 100% interoperable. There are no exceptional cases and you do not have to think in two worlds. You can invoke Xtend code from Java and vice versa without any surprises or hassles.

So, the external classes being used come from Java.

VSCode is a better choice at this point. Development on ESHD stalled and VSCode will become the recommended editor when 2.2 stable gets release, I suspect, and ESHD will be deprecated.

Note that the OH 2 Rules Doc is largely the same as the 1.x docs that OP found to be incomplete and inadequate.

Also be aware that VSCode is open source and I’m not sure if it shares anything in common with Visual Studio.


Yeah but in his defense, the OH2 rules doc doesn’t have that linked collection of sample rules… I think that is what he really is looking for and admittedly missing from the OH2 doc.

LOL, well, not sure why they share common naming. I suppose for all I know M$ stole the name.

Agreed and I’m opening an issue right now to generate some simple rules to include, probably in the Beginner’s Tutorial. Thom and others will probably want to weigh in on where they should go.

OK, well MS is the primary contributor so I suppose they share that in common.

Thank You Guys!
that made things a bit clearer for me - especially the post from @rlkoshak! …so I think I have to dig deeper in Java programming like @ganesh.ingle wrote. Now I focus on learning the Java/Extend syntax to get further :slight_smile:
And maybe it was overdue to learn Java anyway :wink:

Cheers Dan

So here is my first rule I created.

Explanation: If my Broadlink RM3 receives a certain command it should switch and dim my lights.
(the RM3 is controlled via WLAN and sends IR commands to my TV)

When I switch TV ON/OFF I can see this in events.log of OH2:

2017-12-08 11:23:24.936 [ItemCommandEvent          ] - Item 'TV_Livingroom' received command TV_POWER_ON
2017-12-08 11:23:24.939 [ItemStateChangedEvent     ] - TV_Livingroom changed from TV_POWER_OFF to TV_POWER_ON

2017-12-08 11:23:23.527 [ItemCommandEvent          ] - Item 'TV_Livingroom' received command TV_POWER_OFF
2017-12-08 11:23:23.535 [ItemStateChangedEvent     ] - TV_Livingroom changed from TV_POWER_ON to TV_POWER_OFF

But my rule is not triggered I think, because it won’t work. don’t logs my ‘TVEvent’ or is this logged elsewhere?
When I switch my light-items manually it works fine… Maybe my syntax is not right? Can someone please take a look?


rule "Switch Ceiling and din Lights when TV state changes"
    Item TV_Livingroom.state changes
logInfo("TVEvent", "TV triggered")
    if( TV_Livingroom changed from TV_POWER_OFF to TV_POWER_ON ) {
        logInfo("TVEvent", "TV ON")
        sendCommand(B1_ALL_Brightness, 75)
        sendCommand(B1_CH2_Color, OFF)
    else if( TV_Livingroom changed from TV_POWER_ON to TV_POWER_OFF ) {
        logInfo("TVEvent", "TV OFF")
        sendCommand(B1_ALL_Brightness, 100)

please point me in the right direction how to comfortably debug this rule

thanx Dan


I also tried:

    Item TV_Livingroom.state changed

    Item TV_Livingroom.state received update

    Item TV_Livingroom.state received command

    Item TV_Livingroom received update

    Item TV_Livingroom received command

none of them work…


rule "Switch Ceiling and din Lights when TV state changes"
    Item TV_Livingroom changed
    if( TV_Livingroom.state == "TV_POWER_ON" ) {
        logInfo("TVEvent", "TV ON")
        sendCommand(B1_ALL_Brightness, 75)
        sendCommand(B1_CH2_Color, OFF)
    else if( TV_Livingroom.state == "TV_POWER_OFF" ) {
        logInfo("TVEvent", "TV OFF")
        sendCommand(B1_ALL_Brightness, 100)

Sorry it should be changed not changes!

Thanks a lot @Nic_P this works like a charm! But none of my logInfo is shown in events.log is this logged anywhere else or why are they not displayed??

Anyway great job

ahh btw. could someone tell me why the “changed from XX to XX” thing won’t work?
Edit: is this maybe because this will not work in an ‘if’ clause??

cheers Dan

If you login to the karaf console you can use log:display or log:tail
I’m not sure where the actual log files are stored but this works for me

@ganesh.ingle, did you look into the JSR223 add-on at all? It lets you write Rules in Jython, JavaScript, or Groovy. For Rules type logic that would be a bit better of a fit than creating a new Binding for Rules Logic. It is also a whole lot easier to get started given the challenges many face setting up the IDE environment to build Bindings.

It is not as well documented but there is a hardcore set of OH users who are doing some quite amazing things with it.

Yes, they are logged to openhab.log.

That is correct. The changed from XXX to XXX is only valid in Rule triggers. To do that sort of comparison in a Rule there are a couple of ways to do it. Perhaps the easiest:

Besides the implicitly available variables for items and commands/states, rules can have additional pre-defined variables, depending on their triggers:

receivedCommand - will be implicitly available in every rule that has at least one command event trigger.
previousState - will be implicitly available in every rule that has at least one status change event trigger.

Which means you can:

if(TV_Livingroom.state.toString == "TV_POWER_OFF" && previousState.state == "TV_POWER_ON")

The second way you can do this is using persistence and the previousState method, but that requires more configuration to set up so I’ll leave it as an exercise for later.

Almost everything that gets tailed in the karaf console get saved to openhab.log which is in the same folder as the events.log. For an installed OH that is /var/log/openhab2/openhab.log, for a manual install that is $OH_HOME/userdata/logs/openhab.log.

Thanks again @rlkoshak this really helps getting started. Nice to have someone who explains things easy and understandable…

I agree, but it is not yet ready for general use. It is not yet feature complete and the docs are wholly inadequate to suggest its use for new users.

I would not push Dan to its use yet unless he is OK trying to figure it out on his own with adequate docs.

for shure :wink: thats why I’m very happy to get this support from @rlkoshak but I don’t take this for granted …

I don’t like the rule engine very much in this stadium it’s not flexible enough for my purposes I think. And I like to see which code is executed so I stick to rule files… The rule engine seems like a blackbox to me -


Just to be clear, the web based one is the Experimental Rules Engine. I only bring this up because some users use “Rules DSL” and “Rules Engine” interchangeably to refer to the text-based Rules language. I want to avoid confusion on that point.

If you already know a programming language, you might want to look at the JSR223 add-on which will let you write rules in Jython, JavaScript, or Groovy.

The ESHD was pretty good before development stalled and the VSCode with openHAB extension is as good as any IDE I’ve ever used for Java development.

Note though that the language server development and integration for full syntax checking is only available on very recent snapshots. Once 2.2 stable is released, I suspect ESHD will go away for good.

VSCode has (or will have depending on your version)

  • syntax checking
  • code highlighting
  • code autocomplete
  • direct links to docs from inside the editor
  • code snippets include code snippets from the Type Conversion and Design Pattern articles
  • terminal
  • built in browser to observe sitemap updates as they are made
  • Thing, Item, Channel, and Action aware so it will highlight problems with Item names in Rules and the like
  • support for refactoring
  • integration with version control

Pretty much everything one expects out of an IDE.