What's the deal with Python rules in OpenHab 3?

You can write Python rules in OH 3 today. However, to make doing so easier and more convenient there is a Helper Library that implements a number of annotations and library functions to make interacting with the openHAB Java classes more convenient.

The Rule engine is complete and works just fine.

For what ever reason, the Helper Libraries are not yet updated to work with OH 3. But when they are there should be an add-on that one can install to get those available. In the mean time one can manually install the library from GitHub by pulling the PR with the fixes for OH 3.

The answer to that question is going to be the same (or very nearly the same) in any of the rules languages.


import java.time.ZonedDateTime
var now = ZonedDateTime.now()
if now.isAfter(items["MyDateTimeItem"].getZonedDateTime()):


var ZonedDateTime = Java.type("java.time.ZonedDateTime");
var now = ZonedDateTime.now();
if(now.isAfter(items["MyDateTimeItem"].getZonedDateTime())) {

Rule DSL


or if that doesn’t work

if(now.isAfter((MyDateTimeItem.state as DateTimeType).getZonedDateTime)){

For the most part, in Python, anything that is a part of Python 2.7 is available by default. Other libraries pip type libraries can be installed but it requires a special procedure. But most of the stuff you will be doing in rules will be interacting with openHAB. And that is generally going to be the same no matter what language you are using as you will be interacting with the openHAB Java Objects. It’s far easier to answer specific questions than to just dump the javadocs on you.

But in general:

Rules DSL: Pretty much everything you can use will be included by default. That’s why you don’t see an import for ZonedDateTime and you can just access now without calling the method on ZonedDateTime. But there are a lot of things that can’t be accessed (e.g. the Item Metadata Registry). Rules DSL also does not support libraries.

Python/JavaScript/Groovy: Except for the ItemRegistry (ir, Item states are available through the items dict), just about anything from openHAB you’ll need to use will need to be imported. That’s the sort of thing the Helper Library takes care of for you. Note that I’ve personally added an Issue to get more of this stuff added to the default context so we don’t have to import it.

Blockly: Not really complete at this time.

Probably not. At some point I suspect we will get GraalVM Python 3 support at which point you’ll have a choice between sticking with Jython (as long as it remains viable) and GraalVM Python 3. But it will likely at most require some minor edits (similar to what is required to rules to go from a major OH release anyway).

No, it’s completely compatible and there are a number of users using it. It’s the Helper Libraries on the main branch that are not compatible because OH 3 introduced a number of breaking changes (the move from Joda to ZonedDateTime, some core openHAB Actions moved, etc.). These are all fixed in a PR that has not been reviewed or accepted for some reason.

That sounds like a horribly over complicated configuration. Why this approach? Why not use the MQTT binding to talk to MQTT directly? Why involve Exec and Python at all?

tl;dr and conclusion: The Python add-on works just fine. The Helper Libraries are not yet available as an add-on but can be manually installed. The few minor changes required to make the Helper Libraries work with OH 3 are available in a PR. The Helper Libraries make interacting with openHAB easier but are not required (I’m not using them).

If your main concern is “staying close to the core” and reducing dependencies on extra stuff, I would recommend using JavaScript instead for rules. It comes by default (no add-on needs to be installed). However, at some point in the future this too will be updated from Nashorn JavaScript to GraalVM JavaScript at which point there will be some minor changes required to your existing rules mainly having to do with how libraries are loaded and used in the rules.

Your best source for “how do I do X in Python” will be looking at the Helper Library docs and the Helper Library code (if you don’t want to use the Helper Libraries themselves).


If you want sweet and short rules with little syntax have a look a the jRuby implementation, short sweet and fast

It does also require helper libs to be installed, but it interacts directly with openhab

1 Like

Don’t get me wrong. From what I saw, HABApp would be wonderful to have, if it was something I wanted to use. Unfortunately, in my conservation of potential points of failure, its a worst case scenario.

I appreciate your get up and go to see a hole in the community and fill it with such a great product. I wish there was more of that around. When you got to the choice of “should I put my resources into developing a standalone application that has a high risk of being superceded overnight one day?” you said “yes”, where I said “no” :wink:

This will be considerably quicker to read than it was for me to decipher and perform, so please enjoy…

SSH into openhabian machine as openhabian

Make a directory to work in.

openhabian@openhab:~$ mkdir -p tmp/py

then: (Download the OH3 version of the openhab helper libraries for OH3, extract them, isolate the ones noted as required on this page and save the whole automation directory and all its children to the conf share directory.

cd tmp/py
wget https://github.com/jimtng/openhab-helper-libraries/archive/oh3-patch.zip
unzip oh3-patch.zip 
mkdir -p exp/automation/lib/python
mkdir -p exp/automation/jsr223/python
cp -vr openhab-helper-libraries-oh3-patch/Core/automation/lib/python/core exp/automation/lib/python/
cp -vr openhab-helper-libraries-oh3-patch/Core/automation/jsr223/python/core exp/automation/jsr223/python/
cp -vr exp/automation /etc/openhab/

Then back in the OH3 UI, create one of the example scripts that came with the download

  • Go* to Rules
  • Create a new rule (+)
  • Fill in the following fields:
    • Name: Jython Hello World (cron decorators)
    • Description: This is an example cron triggered rule using decorators
    • Tags: Test tag & Hello World
    • When: (Add Trigger)
      • Time Event
      • on a schedule (cron)
      • Cron Expression: 0/10 * * * * ?
    • (and that reports back: Every 10 seconds )
  • Done
  • Save

Then in the Then section:

  • Add Action

  • Run Script: Python (2.7)

  • And on the Edit Script screen

    from core.rules import rule
    from core.triggers import when

    def hello_world_cron_decorators(event):
    hello_world_cron_decorators.log.info(“Hello World!”)

I then click Save, then Run Now and get this in the logs

2021-01-23 23:15:00.395 [ERROR] [e.automation.internal.RuleEngineImpl] - Failed to execute rule ‘a39174d329' with status 'RUNNING'
2021-01-23 23:15:10.400 [ERROR] [e.automation.internal.RuleEngineImpl] - Failed to execute rule ‘a39174d329' with status 'RUNNING'
2021-01-23 23:15:12.342 [WARN ] [jython.core.log                     ] - The 'configuration.py' file is missing from teh python.path!

I try:

import java.time.ZonedDateTime
var now = ZonedDateTime.now()
if now.isAfter(items["MyDateTimeItem"].getZonedDateTime()):

…as per your

The answer to that question is going to be the same (or very nearly the same) in any of the rules languages.

and get:

[internal.handler.ScriptActionHandler] - Script execution of rule with UID 'd7add55e50' failed: <eval>:1:0 Expected an operand but found import
import java.time.ZonedDateTime
^ in <eval> at line number 1 at column number 0

I later came back and realised I should have put in a real item. So I amended the script to:

from core.log import logging, LOG_PREFIX
import java.time.ZonedDateTime
log = logging.getLogger("org.openhab.core.model.script.MyLog")
\# Note: removing "var " from the front of this next line stops it from failing
now = ZonedDateTime.now()
if now.isAfter(items["LocalSunrise_StartTime"].getZonedDateTime()):
    log.info("after sunrise")
    log.info("before sunrise")

…and got back

2021-01-24 02:23:27.487 [ERROR] [internal.handler.ScriptActionHandler] - Script execution of rule with UID 'tryJython' failed: SyntaxError: no viable alternative at input 'now' in <script> at line number 4 at column number 4

when I had that var in there, and then without it:

Script execution of rule with UID 'tryJython' failed: NameError: name 'ZonedDateTime' is not defined in <script> at line number 4

As you can see, I’m not shy. I’m not trying to get someone else to do all the work for me. I’m working with the information I have at hand and am absolutely stuck.

Your best source for “how do I do X in Python” will be looking at the Helper Library docs and the Helper Library code (if you don’t want to use the Helper Libraries themselves).

My best way of doing this is finding someone who can commit to an official source and I can go from there.

Weeks I have been pouring through discussions and I am still no closer to being able to run the most elementary scripts. I was doing fine with OH2.5 but when I upgraded because persitance just absolutely refused to work, and because I was assured it was officially upgraded, I’ve hit nothing but roadblocks in trying to write automation.

I’ll write up documentation myself if no one else has time, but seriously, I can’t find anything solid to teach.

It’s far easier to answer specific questions than to just dump the [javadocs](http://www.openhab.org/javadoc/latest/) on you.

Not at all. Have you heard the old “teach a man to fish” theory?

I’ve considered javascript, but havent even worked out how that would work yet. I might be stuck in the “but Javascript is client side” paradigm.

Except for the ItemRegistry (ir, Item states are available through the items dict), just about anything from openHAB you’ll need to use will need to be imported. That’s the sort of thing the Helper Library takes care of for you.

How about a short page with a crash course on library importing for Openhab 3? I can’t be the only one finding it difficult to just get things going.

When I try to apply the logic that its all Python and Java anyway so it shouldn’t be a problem that I’m in a particular environment, I find there’s enough issues coming up that Google has never ever heard of that its clearly not a straightforward implementation.

I come from a Javascript, CSS, PHP, SQL, Basic, VBasic, etc world where life s good because everything is documented. If I want to know how to do something, I describe it in my head and then find the way to describe it in my chosen language. References are plentiful and very verbose. Forums are full of people who will give you absolute answers to your questions, and who were baptised by fire in the coding forums where useless: why do you want to do that when… questions are flamed mercilessly.

I wish I had time to go down every dead end I find. I’ve been doing it a lot and I’m learning a lot about what doesn’t work, and often why, but I’ll be 60 in 11 years and I don’t have all the time in the world left to me.

I posted this topic last night, my time. I woke up today to your response and wanted to take my time going through everything before I got back to you. That then stretched out to working out what a PR is, wondering why you’re calling it a PR when I don’t think it actually is, wondering why it took until today before I found out that PRs existed, trying the suggested “PR”, searching to make sure the one I found that is actually called something entirely different is in fact what you’re suggesting (I still can’t be sure), documenting everything I did, addressing some of the off topic points that came up, spell checking, formatting, posting… and still I am no closer :frowning:

OpenHAB could be massive. I chose it because it showed the best potential for the future. But if we can’t make people understand how it works, it will only ever be a weird program that annoys hobbyists.

Hi Ben,

I am the one who made the PR (Pull Request) to the helper libraries. I am not the creator of the library. I am just another user of the library who faced an issue during my upgrade from openhab 2.5 to 3.0 and tinkered a bit with the helper libraries to make it work on openhab 3.0.

However, I am using the rule system completely through file-based system. I do not use the openhab 3’s GUI based rule creation, and I am unfamiliar with how the helper libraries would work within the GUI rule system. This is not to say that it’s not possible. I simply do not know because I am quite happy with my file-based rule system.

So if you want to use the file based rule system, perhaps I can help pointing you in the right direction on how to get your rules working, purely as a user-to-user assistance.

Also, whilst all my rules were written in Jython, and in RulesDSL prior to that, I am slowly migrating them to JRuby. Right now I have some rules in Jython as they were from openhab 2.5 and some migrated to JRuby. Prior to discovering the JRuby option, I have never programmed in Ruby. I found it so much nicer though. It’s like Perl and Java but a lot more fun and compact.


The instructions for installing the Helper Library include a a step to create automation/lib/python/configuration.py. You skipped that step. Which instructions for installation did you follow?

Also note, if using the Helper Libraries, and especially if you will be creating and maintaining configurations for lots of instances, why create the rules through the UI in the first place?

I may have shown the import incorrectly. I haven’t used Python for a few months. Maybe it needs to be

from java.time include ZonedDateTime

It’s nothing specific to OH. Look up how imports work in Python and do that.

Python support is what it is in OH right now.

So why change? Rules DSL and. rules files are still supported the same as they ever where. You don’t have to use any other language. You don’t have to use the UI. You can continue on as you always have.

For Python you’ve already done it.

from core.log import logging, LOG_PREFIX

Note that this syntax is defined by Python, not openHAB.

For JavaScript see OH 3 Examples: Writing and using JavaScript Libraries in MainUI created Rules

For Rules DSL you are out of luck.

The docs are the way they are because no one has volunteered to write them better. Id write some myself and it’s on my to-do list but I’ve even more people bitching about the docs for Pages than I do for Rules. And frankly, a lot of the problems are caused by people who have run with Rules DSL rules for years suddenly deciding they absolutely must rewrite everything in a language they are unfamiliar with in a way they are unfamiliar with despite the fact that all the knowledge and work they already have with. rules files are still valid and still work.

The Helper Libraries are not a part of the openHAB project itself. Unless and until it becomes so, it will have it’s own documentation. I can’t fix that.

Python and JavaScript and Groovy all have their own syntax and ways of doing things like importing libraries, iterating lists, etc. I can’t fix that either. One would presume, and perhaps it needs to be said, that the OH docs are not going to teach you how to program in theses languages. They will cover how to interact with OH 3 stuff but not fundamentals to the language.


Thanks Jim :slight_smile:

The link I posted above showing where I got my Jython libraries from, is that the pull request?

You’ve definitely piqued my interest in Ruby. I’ll be having a look :slight_smile:

@NetDirection I think you are trying to do something I find myself doing often enough: trying to run before you can walk. You are ripping through getting automation up and running in Python faster than I’ve seen anyone else in terms of all the different subjects you’ve touched on in this post, but you seem to be missing some details in your haste.

As Rich stated, you missed step #8 in the manual install instructions. I’ve lost track of how many people have missed that one.

To echo Rich, I don’t know how the libraries will work when using GUI rules either. They were written before it was possible and are largely focused on making rule creation in files easier. I’m sure most of the utility functions will work in the GUI, but it hasn’t really been tested yet.

Also it is going to take a little time to get your head around what it means to be running in Jython not CPython. The changes seem unnoticable at first, but as you evolve and get into more advanced things like interfacing with Java classes you will have to adapt.

Your import needs to be:

from java.time import ZonedDateTime

I’m working on stub files for openHAB and the Helper Libraries that will greatly improve the coding experience for Python scripts and libraries by providing type hints. They are lacking polish still and I am hoping to discuss with the maintainer of the Helper Libraries before publishing them, but if they are done before I hear from him I will likely publish them myself in the interim.


The page I linked to and the associated GitHub zip file

Can you please link to the instructions you are talking about?

I’m envisioning a situation where many people are running OpenHab in their homes and they pay someone like me to keep it ticking over for them.

In that scenario, they will be playing with the automation scripting themselves. They will need to be able to use the UI without having to call me every 5 minutes.

And if they are still calling me every 5 minutes, I will need to know the answers to their questions.

Let me stop you right there. I’ve learned over the past week that unless someone is talking about using Python in OH3 UI in January 2021, and has successfully done what they are saying under those exact conditions, I’m going to find that no matter how helpful they’re being, it is utterly useless to me at this point.

I’ll try your suggestion when I’m back in front of my computer, but don’t be surprised if you feel the slight hint of a swear word being mentally transmitted around the world to you a bit later.

You get how that communicates exactly nothing, right?

For those who missed it the first time, I’ll repeat it. I upgraded because a major release implies fitness for purpose. What I found was that the change in Java version broke what I had learned in 2.5 and I’m having so many problems fixing it that I’m stuck at the point of searching for a scripting language that will work.

I’ve imparted no knowledge. I have essentially repeated, like a parrot, something I saw somewhere else.

This is not a crash course.

Delegate. I’ve volunteered to help. Select a group of helpers and guide them in creating this content for you.

So a mass of people have spontaneously and individually decided to do the same thing in opposition to what you expect to be normal and reasonable? Is it possible you’ve made assumptions that don’t bare out in the real world, and these people are just flowing with where the tide takes them?

My keyboard also isn’t covered under the OpenHab project, but I need to understand how it interacts with it.

Fortunately there’s no specific things I need to do with a keyboard to function normally in OpenHab, but if there was, it would be pointless to not make it clear what has to be done.

No it doesn’t need to be said, it would be ridiculous for me to expect you to teach me how to code.

When the OH3 docs “will cover how to interact with OH 3 stuff” will be a good time and reduce the amount of posts along these lines.

I wish this didn’t have to be said, I really don’t like being the ahole in all this, but none of the trying stuff that doesn’t work, answering questions about why I’m trying to do a specific thing, responses that literally say they don’t know the answer, responses that worked in a different version so presumably they work now (but don’t), or responses that don’t get me the simple statement I need so I can move onto my next line of code all take time to process, investigate and reject. It’s very frustrating. I shouldn’t have to literally beg people to stop going off topic.

So far the best response has suggested JRuby.

If it’s cool with you, I’ll put together a summary of these responses as an answer to my initial question and mark that as the solution.

I’ll get you to sign off on it first.

It’s going to include the phrase “not yet fit for purpose and there is no development roadmap”

Woo hoo! Progress :smiley:

I worked out import instead of include myself and got this…

2021-01-25 03:34:02.632 [WARN ] [jython.core.log                     ] - The 'configuration.py' file is missing from teh python.path!
2021-01-25 03:34:02.661 [INFO ] [org.openhab.core.model.script.MyLog ] - before sunrise

So that’s positive.

Can someone please direct me to this illusive step #8? I’m convinced I haven’t seen anything with 8 steps listed.

I had assumed you read the manual installation instructions to get the libraries installed

1 Like


Step 8 is the one that has you create (or to be more specific rename) the configuration.py file.

Very well then. Good luck!

Firstup a primer. Look for the Just tell me already!! title down below if you already know all this.

Openhab has included a python rule engine into its UI in OH3. This means you can write and interact with your own python scripts inside the web interface rules section. When you’re building a rule in the UI, one of the options for Then will be Python scripting.

At this point the Python rule engine uses Python version 2.7, so once setup, you’re basically just exploiting your Python 2.7 skillz. How cool :slight_smile:

To get setup, Openhab 3 Python in the UI is very nearly ready to go, but there’s a few parts missing.

To be fair, the Python engine is there in its entirety, so you can write Python code, but there are very few available libraries available to you.

You can absolutely reinvent the wheel yourself and get things happening, but the more common practice is to include standard Helper Libraries that do a lot of the work for you. Certainly whenever you ask someone “How do I…?” they will reference libraries and the functions therein rather than breaking down the code in those libraries.

But fear not, while Openhab 3 doesn’t yet have a bundled set of libraries to work with, some of our diligent community members have picked up the slack.

Just tell me already!!

@5iver has upgraded the old OH2.5 Jython libraries and @JimT has made them available as a Pull Request.

You can find the package here: https://openhab-scripters.github.io/openhab-helper-libraries

And the instructions for installing are here: https://openhab-scripters.github.io/openhab-helper-libraries/Getting Started/Installation.html (The link to the latest package version for download is in Step: 7)

(Actually, I haven’t followed the full list. I found out about all this in non sequential increments so I was desperately just trying to patch. See below for a breakdown of what I did and didn’t do)

Once you’ve got them in, you’ll need to know what the libraries contain and how to use their functions, you can read into that here: https://docs.python.org/2.7/

You’ll also need to know how to access OpenHab components from within your code. Item states for example. You’ll find a nice primer on this here: https://openhab-scripters.github.io/openhab-helper-libraries/Guides/But How Do I.html#get-the-state-of-an-item

I can’t guarantee this is all perfect, but as a noob, I discovered what I detailed above and managed to get a Python scripts working from the UI.

So this exact process worked for me?

I actually didn’t follow the full list from the Jython Libraries Instalation Instructions. I found out about all this in non sequential increments so my process was actually:

  • Install Python Add-on in: UI -> Settings -> Add-ons -> Automation + Jython Scripting

  • Download and extract … you know what, I listed all this in another reply, go look at that if you must know. Its the long one with heaps of code references.

  • Work through the install guide, skipping the bits I didn’t think I had to do

    1. skip
    2. I did this but didn’t have to. It did answer a question in my mind about logging though.
    3. See 2
    4. Skip, come back to it if I need to
    5. Didn’t think I’d need as I already have a Python interface in the UI
    6. Skip. Can do a restart later
    7. Did this. It is a newer version the the other one I downloaded.
    8. Did this, only did /automation/lib/python/, couldn’t locate another configuration.py.example to rename
    9. Did this
    10. Skipped. Thought I might have to come.back to it, but have been assured it is already taken care of in OH3 by the add-on.
    11. See 10
    12. instead of doing this, recreated the same conditions in UI. Basically, you just want to write to the log file every 10 seconds
    13. did a service openhab restart because of not having shut it down in step 6
    14. Not a real step. I think it was included to stop there being just 13 steps. That would be unlucky and invite problems :wink:
    15. see 14

Any Questions?

1 Like

That can’t seriously be your take away from all this. If I were you and i wanted to focus on one shared idea, I’d look at the one that lightens my workload.

Have a look at my reply above.

If you agree, and no one else objects, I’ll mark it as the solution.

1 Like

You have been flying to extremes in this thread and implied that Rich is not doing the right work. Rich is the most helpful user on this forum as far as I’m concerned. He has written countless how to’s and answers maybe half of all the topics opened on here by himself. There is no team for him to delegate to, everything about openHAB is volunteer based, everyone contributes what they can when they can.

That said, your above write-up is excellent, thank you for making such a concise and accurate reference. Steps #10 and 11 can be skipped entirely on OH3, the new add-on takes care of those internally.


You said I wasn’t being helpful. If I’m not being helpful and “silently cursed” for my efforts I will spend my time elsewhere. Doing anything else would be a waste of both of our time.

Frankly, once you said that I stopped reading and have moved on. I don’t have an infinite amount of time and can’t afford to waste it being unhelpful.

1 Like

Hello to all and good evening,

I ended in this thread coming from Jython helper libraries for OH3

After migrating and setting up jython in OH3 I keep getting this entry in the logs at every start-up:

2021-01-29 22:26:37.804 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.805 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.806 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.811 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.819 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.821 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.821 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.824 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.824 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.828 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.828 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available
2021-01-29 22:26:37.832 [INFO ] [ab.core.service.AbstractWatchService] - ScriptEngine for py not available

Could someone help me how to get this sorted?

Thanks for all your help.

Best regards

Hello again,

I only now saw this thread marked as solved so I thought it would be better to post on the other thread.

Sorry and thanks again.

Best regards.

1 Like

You need to install the Python addon.

@rjduraocosta @rlkoshak this seems to happen on startup no matter what. Seems the Python Script Engine is not ready when the File Watcher scans the files. Once the Python SE is ready it will load all the Python files.

1 Like