What is the “best” way to write rules in OpenHAB 3?
I am aware that “best” depends on a lot of factors and personal preferences, so I’ll outline my needs very quick
I am a Java, Python and Groovy developer myself, and I like scripting more than clicking myself around a UI (although I have migrated my items almost completely to the UI based model when migrating to OH3). Currently I am using the Jython Automation Add-On and the openhab-helper-libraries by openhab-scripters to allow decorator-based rules. But it seems the openhab-helper-libraries are not actively maintained anymore (last commit is from 2020) and I am afraid some API changes will make the library unusable in the future. Also, Jython is stuck with Python 2.x.
All alternatives I have tried so far fail for some reasons:
Groovy (lacks documentation, cumbersome adding rules and triggers)
JavaScript (really not my language, steep learning curve at least for me)
JRule (too beta, no custom actions yet, no access to OpenHAB internal API)
Rules DSL seems a bit deprecated
What are the folks that originally developed openhab-helper-libraries using nowadays?
I suggest changing your post to be “Best way for me to write rules in openHAB 3”. Just to make this a little less general.
Anyway, this comes up a lot. Rich made a handy chart that I can’t find right now, so I’m just going to cut to the chase since you’re a Python developer:
HABApp runs separately from OH, but integrates nicely with openHAB via the REST API.
FYI, Rules DSL is more than just “seems” deprecated. It will continue to exist in OH3 for legacy purposes, but new users are not encouraged to learn it.
The built in JavaScript should be considered deprecated, though support can be continued when OH moves beyond Java 11. But unless you have a lot of legacy rules already written in it, choose JS Scripting instead if you want to use JavaScript.
Jython is the walking dead. Upstream support has all but stopped and Python 3 support does not seem to be forthcoming. That’s one reason why the helper libraries are not really being worked any more.
JS Scripting and jRuby have the most mature helper libraries. In both cases I think you get as close to a pure environment as possible (meaning you don’t have to worry about “this is really Java but that is really JavaScript”). They also support the standard library distribution mechanisms (npm for JS and gems for jRuby). If you plan on using UI rules, JS Scripting has more features built into it to make that experience better but both are great for text based rules. Both expose pretty much the entire of the openHAB API (or you can figure out how to get to it by looking at the helper library). Note, the JS Scripting helper library is a part of the openHAB project proper and comes with the add-on. For jRuby it’s a third party library you have to install using gem.
Rules DSL isn’t going anywhere but I would treat it as around strictly for legacy support. New users who would benefit from a more limited programming language to start with would be better off starting with Blockly instead.
There is an alternative Java add-on on the third party smarthomej marketplace: GitHub - smarthomej/addons: SmartHome/J addons for openHAB. See the docs for how to enable that as a source for add-ons to install. I’ve not used it not looked at it too closely but it looked to expose
If you like Python and don’t mind running your rule engine in a separate service HABApp is a good choice. It’s pure Python 3.
Also, don’t ignore the rule template marketplace. Someone may have already created a rule that you can just install, configure, and use.
There’s a lot of history there. I’m not sure where a lot of them ended up. I know the owner of the original helper library @5iver has disappeared, and another (@jpg) did most of the work to create the JS Scripting add-on and did most of the initial work on the helper library. I’m not sure what @CrazyIvan359, who maintains the most up to date fork of the helper library and did most of the work to bring it up to OH 3 support is using these days.
I was involved with the old helper library some myself and I currently use JS Scripting add-on (ECMAScript 11) and UI rules mostly, though I do have a library that I publish (can be installed using npm). It’s more utilities than stuff that belongs in the official helper library (most of the helper library stuff I’ve already contributed to the official library). And on the next point release of openHABian (if it hasn’t happened already), that library will be installed by openHABian by default too. It’s mostly generic implementations of design patterns and I also host my rule templates there though those can be installed from the marketplace.
Anyway, I was one who pushed for a lot of the features that got added to JS Scripting to better support UI rules (e.g. cache, autoimport of the library, etc.) and added a bunch of time based utilities to the helper library to make mucking around with time easier (e.g. if I want to schedule a timer to go off at 22:00 today I can create the datetime with time.toZDT("22:00"), or if I want it in 1 hour and 2 minutes from now time.toZDT("PT1h2m") and so on. There’s something like a dozen different conversions it handles.
Note: if you want to write or use rule templates, those are only supported through the UI.
If the learning curve is of concern, you might look at the JS Scripting add-on. Because the helper library comes with the add-on and it’s officially part of the OH project, it has the best set of docs probably of all the languages that are included in the OH docs. The add-on readme is pretty complete and what’s not covered there will have a link to the raw api docs. It’s way easier to learn and use than the older JavaScript. It provides a much more natural abstraction of the openHAB API than the older JavaScript helper library was able to achieve.
Native to openHAB, no signs of it ever being dropped, best documented, most examples
No support for libraries, limited language features
Cannot persist variables between runs of a rule, cannot import libraries
JavaScript Nashorn
Native to openHAB
Based on ECMAScript 5.1, will eventually be dropped when Java 11 is no longer supported.
Does support preserving variables between runs of a given rule.
Blockly
Native to openHAB, graphical programming environment
Not yet complete
Only available through the UI
Jython
Most examples and docs of the non-Rules DSL languages, most mature Helper Libraries
Based on Python 2.7, Jython project appears all but abandoned, it’s not clear a 3.x Python version will ever be finished
Groovy
Least used of the original three JSR223 languages, support for libraries is not as good
GraalVM JavaScript
Most recent ECMAScript version, most easily supports third party standard libraries
Almost no documentation, installation of the add-on breaks Blockly and Nashorn rules (JavaScript transformation too?), work very differently from the other languages (harder to take knowledge learned on one and move to another language)
Not clear how/whether they work
jRuby
Very native Ruby approach
Not yet merged into openHAB main, work very differently from the other languages
Not clear how/whether they work
Java
Full Java IDE support
Still under development
Not clear how/whether they work (probably not)
HABapp
Full and native Python 3 rules engine
Runs as a separate service and interacts with OH through the REST API
NA
NodeRed
Nice graphical interface
Runs as a separate service and interacts with OH through the REST API
JRule is not so Beta as you would think, script-actions are being handled and there are workarounds if you want to use it. If you take a look at github there are several PRs and it is continuously evolving with several peoples contributing.
Personally for me JRule has been a game changer, I can write rules easily, even more complex logic and getting them to work right away. You can access OpenHAB core from JRule, nothing is prevting you from doing that.
If you are a Java developer getting started with JRule does not require a lot of time. I would suggest you test it out. You are also welcomed to contribute if you want to.
First of all thanks for all your input. Helped a lot to get a good overview and confirmation of some of my suspicions, mainly that I should get away from my Jython rules
@Seaside I tried JRule installed from the marketplace and I like the approach very much conceptionally, especially being able to use IntelliJ for development. I stumbled upon the custom datatypes instead of OpenHAB’s native types, and I assumed that is because the internal API is not accessible or at least discouraged to do so. A minor drawback was also that the rules were not visible in the UI.
Then I read @rlkoshak’s mention of smarthomej/JavaRule, which at first sight seemed to have more of what I wanted, like using the internal datatypes (which makes it easier for me to switch between add-on and rule development), more triggers, more generated code (i.e. Things and Actions) - but maybe that has changed in the latest JRule snapshots - and the rules are shown within the UI. The annotation’s naming occurs more natural to me, too.
So I guess I will implement some rules with either engine and then decide to which one I’ll stick.
We seem to need an authoritative list (table?) That is regularly updated and pinned to the top. Maybe make it a wiki so it can be updated by the developers of the respective libraries? Otherwise we end up with the same information spread across multiple threads with various levels of relevancy to the current state of the matter.
If it’s something permanent and kept updated it should probably go into the docs. @florian-h05 and I are working on a complete revamp of the rules documentation and I’m sure we can find a place there to put something like this.
However, I don’t think it will solve the fact that people keep asking the question. People just don’t read the docs that closely.
July 2021 is a long time ago, and since then much (really much) work has been done on many of the languages. I can only speak for JS Scripting and Blockly, they both have developed much. As @rlkoshak already mentioned, JS Scripting got it’s own helper library, that covers most parts of the openHAB API and IMO, JS Scripting also has the best docs.
Blockly also greatly evolved, many new blocks were added to extend it’s functionality and @stefan.hoehn and me are currently working on porting Blockly to JS Scripting to use gain advantage from it’s extensive helper library.
IMO you are absolutely right, the only thing is we have to decide on a place to put this. Currently I am busy with the JS Scripting addon, the helper library and the Blockly porting to JS Scripting, but I’ll try to also contribute to the docs again.
I totally understand. Getting the new concepts page updated was huge and I’m glad we got that done. I’ve contributed far less to this issue than I intended and hope to get some time over the holiday break to contribute some more (as well as upgrading all my rule templates to use my library and the new privateCache and sharedCache).
With our current proposed outline, I think the concepts page or a brand new Intro to Rules configuration page we don’t currently have would be the place. I don’t see it as going on any of the other proposed pages.
Since we are talking about making a brand new top level section for rules like there is for the UI, I wonder if a new intro page makes the most sense and we can put it there.
Agreed. We just have to be extra careful not to be too biased in the official docs. We all have our preferences and biases. We should not unduly let those influence new user’s choices.
It’s mostly generic implementations of design patterns and I also host my rule templates there though those can be installed from the marketplace.