JSR223 Jython Scripting Helper

Deutsch

Here I would like to briefly introduce my own openHAB Rule Helper classes. The reason to create them was because of the syntax of the JSR223 Jython interface was too complex and complicated to write a simple Rule.

There is already a GibHub project which offers a high degree of abstraction. This does not go far enough for me, which is why I designed my own solution. However, it is based on the existing solution and extends it.

Example of a simple rule

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
@rule("door_bell_notification.py")
class DoorBellNotificationRule:
    def __init__(self):
        self.triggers = [ItemStateChangeTrigger("Bell_State", "OPEN")]

    def execute(self, module, input):
        self.log.info(u"Bell was triggered"")
        if itemStateOlderThen("Bell_Last_Change", getNow().minusSeconds(30)):
            sendNotification("Bell", "Bell rings", "https://yourServer.de/cameraStreetImage")
            sendMail("Bell rings", u"Someone rings on the Door", "https://yourServer.de/cameraStreetImage")

        postUpdate("Bell_Last_Change", DateTimeType())

Rule Annotation

The @rule annotation registers this class as a rule. The contained string “door_bell_notification.py” is needed for logging. My Rule Annotation now offers the following enhancements:

A logger object is provided which uses the previously mentioned string as identifier
Indirect events are automatically filtered out. i.e. If the item “Bell_State” is part of a group and was triggered with “OPEN”, the execute method was called twice. Once for the item and once for the group. This second event will now be filtered out
At the DEBUG log level, runtime information is automatically output
In case of an error, a meaningful stack trace is issued
In case of nonexistent items the rule is skipped. Is important at the startup of openHAB

Methods

Furthermore, my class offers a variety of useful helper methods. They are based on the functionality of openHAB 1.x and should facilitate the migration to Jython based rules in openHAB 2.x.

getGroupMember - Returns all items that are part of a group
getGroupMemberChangeTrigger - Registers triggers for all group members
getChannel - Returns a channel
getItem - Returns an item
getFilteredChildItems - Returns all items that are part of a group and have a specific state
getItemState - Returns an Item State
getHistoricItemEntry - Returns an older Item Entry
getHistoricItemState - Returns an older Item State
getMaxItemState - Returns a max value of an Item States
postUpdateIfChanged - Updates an item state if it has changed
postUpdate - Updates an Item State
sendCommandIfChanged - Sends an Item Command if the state has changed
sendCommand - Sends an Item Command
getNow - Returns the current DateTime
itemStateNewerThen - Checks when an item state has been changed
itemStateOlderThen - Checks when an item state has been changed
itemLastUpdateNewerThen - Checks when an item state has been updated
itemLastUpdateOlderThen - Checks when an item state has been updated
getItemLastUpdate - Returns the last update time
sendNotification - sends a push notification
sendMail - sends an email

Sources

All my used rules are based on this Jython extension. It can be obtained directly from my GitHub Repository.

https://github.com/HolgerHees/openhab_shared/blob/master/python/shared/helper.py

In addition, the classes from the previously mentioned Jython project still need to be installed. The easiest way is to follow the Jython installation guide and then copy everything from my repository into its openHAB python folder

https://github.com/HolgerHees/openhab-config/tree/master/python

Burntime Script

Another problem in openHAB was that rules were started before openHAB was completely initialized. To fix this problem I wrote the “burntime” script.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
log = LoggerFactory.getLogger("org.eclipse.smarthome.automation")

log.info("jsr223: checking for initialised context")

while True:
    try:
        scriptExtension.importPreset("RuleSupport")
        # from openhab.jsr223.scope import items
        # if items != None:
        if automationManager is not None:
            break;
    except:
        # instance = sys.exc_info()[1]
        # log.info(str(instance))
        pass
    log.info("jsr223: context not initialised yet. waiting 10 sec before checking again")
    time.sleep(10)

log.info("jsr223: done")

It is stored under the name “000_burntime.py” in the openHAB Rule folder and started first. It now runs until the openHAB “automationManager” is available and blocks the execution of all other rules until then.

This script can also be downloaded from my GitHub repository.