Where to find available methods and functions for rules

Setup, Configuration and Use Beginners
,
1

Hello Everyone,

I just installed openhab in an odroid and I’m very pleased how good it works with my onlye “smart” device.
Now I have started to play a bit with rules for more advanced functionality and I feel totally lost. I can’t find any reference of which libraries I have to import, which classes are available, data types, methods of each class, scope of the rules/scripts… The wiki on GitHub is very lacky about this.

For example, I don’t know which methods the DateTime variables has. Where is the complete reference ? Can I get the current value of a DataTime variable? How?

Same stuff applies for items. I have no idea which type of data item objects are. I can see that you can get the current value, and not sure if there are several ways, update the current value. For example, I don’t know if I can use a item object to store a counter (or countdown) which is shown on the gui and updated on rules.

Other question, what happens to a timer when it expires? Is it set to null? Is there any special method to check if it has expired?

Any help will be very appreciated.
Thanks and regards

2

Don’t have time for a full answer but I can provide some hints.

Get Designer and use ctrl-space key combo. This will give you all the legal ways to complete a line. For example, if you type the name of an item followed by a door and ctrl-space you will get a dialog with all the methods on an item.

Unfortunately learning which packages to import I’d harder and usually requires searching through the source code or finding examples.

There is a has terminated method on the timer class you can test to see if the timer has expired. Though I usually just set it to null manually as the last line of the timer so I only have to check for null instead of both null and has terminated. Though I recently read that t the timer may be set to null for you.

3

What’s the danger of over-importing?

Right now I’m using the ‘test rule, remove import’ (repeat until broken) method.

4

Thank you Rich for your answer.

I though about using the Designer to make things easier, but that has some problems:

  • Yo need to know beforehand what are you looking for. When you have no idea this is a hard task.
  • The designer does not seems to accept the creation of a new file. You have to open an OH configuration folder. This is a problem for me because I have OH on a headless server, so I would need to export the configuration (maybe a share) and edit it trough the shared folder.

I expected some “reference” document, like most of the languages has, some beginner guides and that stuff. Most of the information that I have found seems to be updated.

For example, did the global variables of a rule survive to rule execution? Can I use them as temporary store between executions?
Another question, how can I debug the execution of rules? It’s logging the only way? Any better way?

A timer can set itself to null during its execution? That sounds cool.

thanks all

5

It may take up more memory than needed when it runs. It isn’t that big of a deal but it is better to import just what you need.

I highly recommend using Designer. Then you can just remove the import and look for red underlines.

6

I do exactly this; my OH box is a linux box, but my daily driver (and where I run the designer) is windows. (I share the openhab directory with samba.) I don’t really see a downside to this approach, especially if both pieces are on the same LAN. It’s not like whipping around video files, ascii text files are about the easiest load you can find!

I’m already using designer but this sequence never occurred to me. Thanks!

7

Not sure what you mean by this. That is true whether you are using Designer or anything else.

Indeed, Designer is designed to work with a full OH config, not individual files. I needs this because things that are in on file can impact other files (e.g. Designer knows all the Items in your .items files and can tell you if you refer to a non-existent Item in a .rules file). But indeed, it doesn’t let you create a new file from within it. I usually just touch the file I want to create and hit F5 in the tree pane in those now rare cases where I need to create a new file.

Most people either share their config folder over the network or use some sort of source control mechanism to sync between the dev machine and the headless machine. I use a personal git server.

Your reference documents are:

  • Wiki, in particaulr the Rules page for the structure of Rules and details about how they are loaded, work, etc. A lot can be gained by studying the examples on the wiki and the demo as well.
  • Xtend Documentation for specific language constructs like switch statements and the like. NOTE: The Rules language is Xtend like, it is not Xtend and not all features are supported (e.g. you can’t create a class in Rules)

There is no English user’s or beginner’s guide (there is one in German). There will be one for OH 2 but it does not currently exist.

A global variable will keep its state while OH is running so you can use a global variable to pass data back and forth between rules. However, a global variable cannot be accessed out side of the .rules file it exists in. Also, the value of a global var does not get restored when OH restarts or you reload that .rules file. Much of the above is documented in the Rule’s wiki page.

Unfortunately there is no debugger for rules. Logging is about your only choice for debugging rules. However, I’ve found that if you work to keep your rules relatively simple and you take advantage of the mechanisms built into OH (e.g. persistence, storing state in Items rather than global vars, etc) and avoid falling into the trap of trying to program your rules like you would program in Java or C logging is all I need. My average rule length is <20 lines of code and most of my .rules files are under 100 lines of code. If you find yourself with massive rules or complicated lambdas and storing state in global arrays or maps then you should step back and reconsider whether there is another way to do what you want using what is available to you to make it simpler.

var Timer myTimer = null

rule "Timer test rule"
when
    Item MyItem received command
then
    if(myTimer == null) {
        myTimer = createTimer(now.plusMinutes(5), [|
            // do timer stuff
            myTimer = null
        ]
    }
end

When you create a Timer it inherits the same context as the rule it was created in. Thus it has access to all the same variables, objects, classes, etc as the rule did. Thus it can set the variable that holds it to null as I do above.

2 Likes
8

Ok, so what if someone were to try documenting this language? I suppose that would require going through and creating all those pages or finding some utility like JavaDoc to do it all for you.
I also am running OpenHab on a headless server on linux, but my main computer is a Mac, so I’m sure it would be easy to set up a share. But I like using Sublime Text for everything.
Ok, I’m done rambling and hijacking this thread.

9

It is planned for the OH 2 documents as is a user’s guide and beginner’s guide. First we need to set up the documentation infrastructure for OH 2 though.

We are dropping the wiki concept and moving towards something a little easier to manage. If you want to contribute we would welcome the help.

For now though, the Rule’s page coupled with the Xtend documentation is actually pretty thorough, if inconvenient to use. Designer’s intent is to help bridge the gap between the scattered documentation.

1 Like