Some people take somebody saying it can’t be done as a challenge to do it.
OH is very flexible.
This should work actually. You have to import it but lewie’s and Scott’s helper library makes it relative eat l easy.
Writing a script that actually does something useful in JSON isn’t so fun, but it’s certainly possible as you demonstrate. It can be a way for those willing to get started with NGRE despite the limitations of PaperUI.
The PaperUI ised the rest api
Is NGRE part of the PaperUI, or can it be called separately from a Python script, for example?
PaperUI is … well, a UI. Rules is rules.
How would I access NGRE outside of PaperUI then? Is there a documentation link I missed?
Access in what sense? You can edit/create rules with PaperUI, but its not really developed. You can edit/create rules in a JSON file, and import them from karaf console - as illustrated a few posts back.
Once a rule exists, it gets triggered to run by system events, such as an Item update. If you wanted to ‘access’ in the sense of making the rule run, you’d need to cause the trigger i.e. update an Item.
NGRE is like most experimental things poorly documented. @rlkoshak is working on it.
If I am trying to use a different (my own?) UI uncoupled from OH, it could potentially use NGRE to put rules through the REST API into OH.
“Has worked on it” instead of “working”. The documentation has stalled because of limitations in PaperUI and the rapid and huge advancements Scott and company are making to the helper libraries I’ve stopped work on them, for now. I hope to be able to reuse maybe 50% of what is there now when we do pick back up on the docs.
OK, here is a quick tl;dr to explain the moving parts here.
PaperUI is a UI only, like rossko57 says. All that PaperUI does is present graphical elements to the user (forms and buttons) and converts the interactions with those into REST API calls. PaperUI is currently the only graphical way to create NGRE Rules.
The NGRE itself is a Rules Engine that currently supports the running of Rules written in Jython, JavaScript, and Groovy. JSR223 Rules are executed by the NGRE. Rules created by PaperUI are stored as JSON in the JSONDB, but despite this radically different form, these Rules too are executed by the NGRE. To a large extent, the NGRE represents a unification of the Rules Engine. Whether you create your Rules in text files or through whatever replaces PaperUI, it will be executing on the same engine.
So, if you want to start using the NGRE now, you can get started with JSR223 and the Helper Libraries.
The example JSON Yannick posted above is JSON Rules. This is the type of Rule that would be created through a UI/REST API. Instead of being saved to .js files, they get stored as JSON. The biggest difference between JSR223 Rules and JSON Rules is that in JSR223 you have to define your Rules and triggers and such in the code. The Helper Libraries makes this very easy to do, especially with Jython and it’s annotations. In JSON Rules, most of the stuff that defines the Rule is defined in JSON. The “body” of the Rule (in Rules DSL the stuff between the then and end goes in the actions.configuration.script element. In Yannick’s example, its a set of three print statements using JavaScript.
Note that “type” element. You can write your rule using any supported language for JSON Rules, not just JavaScript. Though PaperUI only supports JavaScript at this time. It’s also important to note that the Action need not be code when using JSON Rules. For example, right now I have the following choices for Actions:
- enables or disable rules: this is going to be super powerful; imagine just disabling your night time Rules when the sun comes up, this works with JSR223 Rules too
- execute a given script: see Yannick’s example, this is the closest to what we are used to doing with Rules
- play a sound
- publish an MQTT message
- run rules
- say something
- send a command
- send a web push notification to HABot
As you can see, individual bindings can add their own Actions to the list.
JSON Rules also have the concept of “but only if…” which I don’t think has an analog in JSR223 Rules (@5iver, is that true? I couldn’t find any similar concept in the Rules section of the Helper Library docs). This lets you establish a set of conditions which must be true for the Rule to trigger. Unlike with Rules DSL where all you have are events that trigger the Rule and then you need to use if statements in the body of the Rule to see if there is anything to do, JSON Rules have a separate section for this. As with Actions, you can write a full script for this or use one of the built in conditions (e.g. “it is a certain day of the week”).
Finally, I believe both JSR223 and JSON Rules have the concept of Rule Templates. These are pre-written Rules that you can import into your setup, perform some configurations (e.g. mapping your Item names to the parameters needed by the Rule). This will be huge! No more will we need to copy and paste examples from the forum for users to adopt some code. We can let the experts write the Rules for us and just use them as is.
On the Rules front, the future looks bright indeed.
As for docs, as you can see from the Helper Library docs, the language and ways to interact with openHAB is pretty well documented. There is very little documentation available for JSON Rules. Since JSON rules were never intended to be written by hand, this isn’t surprising. But the part that makes them “experimental” is the limitations of the UI part. The Rules themselves are mature and working very well.
Thank you for the detailed reply. I followed the link yo the helper libraries and got a little excited when I saw Python because I am currently learning & using that at work.
My heart sank when I saw it is Jython which is based on Python 2 which will be completely unsupported in January next year. 
No plans on supporting Python 3? It has been available for many years.
I am also working some on JSON. It is not as scary as XML 
I do not see JSON mentioned in the Helper Libraries.
Until OH can move to a more recent version of Java where Graal VM will be available, these are the only three languages that are available. I believe the target is to move to Java 11, but there are some upstream libraries around the Xtext libraries IIRC (upon which all the text config files OH loads like .items, .rules, .sitemaps, etc) that cannot run on Java 11 or later yet.
The hope is once we have Graal VM, we can support pretty much any language you can think of. I wouldn’t mind playing around with Clojure or some other functional language. Until that happens though, probably OH 3, we are stuck with Jython. If you really want to get started with Python 3 (honestly, for the purposes of Rules writing, I see little practical difference between Python2 and Python3 so even if you get started with Jython now, when Python 3 becomes available it should be minimal effort to move your rules over).
And if you really want to jump in using Python 3 from the start, there is GitHub - spacemanspiff2007/HABApp: Easy home automation with MQTT and/or openHAB. Though because this runs as a separate application it is limited to only doing actions that can be done through the REST API.
Thanks, I saw that . I may look at Jython when I have a chance.
Thank you for your patient explanations & advice.
If you use a snapshot (and soon to be included in 2.5M2), all installed JSR223 supported script engines will be included in the Script Type dropdown for scripted Actions and Conditions. I added this right after 2.5M1 was released.
Unfortunately, all current bindings implementing Actions have used the AnnotatedThingActionModuleTypeProvider, which was not originally implemented for allowing the Actions to be used within a UI, so they will not work. Enhancing this class is being discussed. There is no visual que that Actions and Conditions are coming from a binding or core, so usage can be a little tricky ATM. Binding Actions do work in scripts though.
Conditions are available, but I haven’t implemented them in the helper libraries. They are really only useful in the UI, since they are essentially ‘if’ statements. Eventually, they will be expanded to ‘if/then/else’, which will be a milestone for UI rules, since the rules will no longer be linear paths with a single set of possible Actions. Too soon yet to dive into a discussion about this, and will required integration into the new UI (OH3).
The NGRE is also experimental because the APIs are not locked down and changes to them could break rules. I don’t foresee any major changes being needed ATM though, and development of the NGRE has settled down significantly after the business(es) using ESH stopped contributing. I hope to get a major changes implemented before OH3 though.
There are only some experimental (and TMK abandoned) Jython builds using Python3. When/if GraalVM is integrated, which is the logical evolution of OH scripted automation, you’ll be able to use newer version of Python. I see Rich has mentioned this, and I agree that there is very little you will miss using Python2 for scripting.
There are many other languages compatible with javax.script (JSR223). That repo is a fork from the java.net scripting project, which is no longer available from Oracle. Jython, JS and Groovy are just the most popular for use with OH.
Hmmmm. I’m on Build 1639 and all I have in the list is ECMA Script (i.e. JavaScript).
I’m upgrading to 1640 as I type this (to get the fix for the REST API Docs) and will post back if that changes. I thought I remember you mentioning that this was fixed in PaperUI but doubted my memory when I tried it recently and it didn’t work. Maybe it’s a recent regression? Clearly something changed because prior to 2.5 M1 it said JavaScript instead of ECMAScript.
But it’s possible as evidenced by the “publish MQTT” Action which was my main point.
Which is why I wasn’t surprised to see them listed. But if we want to ever get to a point where users can export their JSON Rules to Python (for example) there will need to be some sort of concept in the Helper Libraries I suspect.
Available doesn’t necessarily mean that they work. There was some significant work a couple years ago to try and get JRuby to work as a suitable JSR223 language. There was some fundamentally technical hurdle that they could not overcome. I’m sure many others on that list can work, but there is at least one that will not. Perhaps jRuby or openHAB has changed since then to the point where it would work.
It’d be fun to write Rules in Scheme though. I have an intuition that the functional paradigm would work quite well for Rules. I just don’t have the time right now to try it out and see if it works.
The list is built from the available ScriptEngines. When you setup Jython or Groovy, you’ll see them in the list.
Binding ThingActions are currently visible in the UI, but they will likely soon be hidden until this is fixed. However, you’ll find that you can’t configure a topic for the MQTT Action, or add an email address, subject, or message body in a Mail Action, etc.
The helper libraries are a filler for interacting directly with OH classes and interfaces until a Scripting API is put in place. There will still be some use for them though (utility functions, experimental functionality not yet implemented in the API, custom ModuleTypes and handlers, etc.). I expect the Scripting API will be around long before someone looks into migrating JSON rules to scripted automation. It would also be easy to migrate a Condition too, since they are just a simple ‘if’ statement.
Adding Conditions is on the list though!
They should all work. However, a language specific ScriptEngineFactory may be needed for special handling of the default script scope. I haven’t tried jRuby, but I believe the issues early on were with the OH1 implementation.
But I do have Jython set up. All I have is a “hello world” script set up but I do have it available. I don’t have the latest helper library, is that required?
Funny – just a couple of days ago I needed to trigger a JSR223/Jython rule based on the online/offline status of an MQTT/Homie device.
I came up with this on my own:
@rule("ServerRoomLightsChanged", description="", tags=["utility"])
@when("Thing \"mqtt:homie300:srvrm-lightsense\" changed")
def ServerRoomLightsHomie(event):
status=event.getStatusInfo().getStatus().toString()
if status=="ONLINE":
global hTimer
if hTimer:
hTimer.stop()
hTimer=0
if status=="OFFLINE":
events.sendCommand(ir.getItem(strItem),OFF)
Am I just lucky to have started in JSR223 to begin with? Would the when thing xxx changed pattern not have worked in Rules DSL? Or is it a matter of ONLINE/OFFLINE status being different for Z-Wave and Homie devices? I’ve only used this with Homie and it works perfectly there.
No, just Jython in the classpath. It’s still working for me on S1634…
I’ll go update and check to see if it might have broken. There have been some recent changes to automation, but nothing that I would have thought that could have broken this.
Thing triggers also work in the rules DSL. Actually, a ThingStatusTrigger was recently added to the NGRE too. I haven’t committed a PR to use it in the helper libraries yet, but it’s coming.
So then, how is that different from the OP question? Is it just the “from ONLINE to OFFLINE” part that doesn’t work, so the logic has to be in the rule itself?
The OP was looking for a generic rule to alert when any Thing went offline… like ‘Member of’ but for Things. In the helper libraries, you can use GenericEventTrigger (not included in the when decorator).
2 Likes
@rlkoshak, the script type dropdown is still populating for me in S1641. If you open an issue in GH, we can troubleshoot it over there.