Edit: changes for Release 1.1.2
I would like to formally announce the release of openhab_rules_tools. Those of you who have followed my postings for awhile will recognize just about everything here, I’ve just made it a bit more formal.
These started out as contributions to the Jython Helper Libraries. For various reasons they were never accepted so I moved them to my own repo.
When OH 3 came out there was a delay between when Jython support was established so I rewrote them as Nashorn ECMAScript 5.1.
Now that JS Scripting has been added to OH and the helper library openhab-js included as part of the add-on, I’ve rewritten the library as ECMAScript 11. This allows the library to be published and distributed via
npm, vastly simplifying the installation process.
This library has a dependency on the
openhab library. However, because this library comes with the JS Scripting add-on, it is not listed as a dependency. Otherwise when you install this library you’ll get the latest
openhab library whether you want it or not.
For now the library assumes that the settings for JS Scripting are at the default which causes openhab-js to automatically be injected into your rules. If you turn that feature off, I don’t know if these libraries will work.
$OH_CONF/automation/js folder run
sudo -u openhab npm i openhab_rules_tools
Look up instructions fro running
npm on your specific OS if not running on Linux.
Lacking at the moment. Look at the files under
tests for examples and the code itself for usage details.
|Name||What it does|
||Class that implements a Timer and updates a passed in Number or Number:Time Item once a second with the amount of time remaining on the timer. Useful for showing how much time is left on a Timer on the UI.|
||Class that allows one to schedule a command or update to an Item in the future.|
||Schedules a sequence of actions with a time for how long after one action before the next action runs. This can be used to limit how quickly commands are sent to a device or create a schedule (e.g. irrigation).|
||A series of functions that implement some common operations on members of a Group, such as getting a comma separated list of their names. There are also some methods that work on generic Arrays.|
||Implements a Timer that keeps calling a function as long as that function doesn’t return
||Implements a class that ignores events that happen too soon after the most recently processed one. This is useful to filter out alerts that may occur more frequently than you care about (e.g. only remind me the battery is low once a day).|
||Does not work well in UI scripts. Some functions that will generate a rule triggered by Items with a given tag or given metadata configuration.|
||Implements all the book keeping required when managing multiple timers in one rule (e.g. one per Item).|
Mostly Deprecated: most of this functionality is now part of openhab-js. A number of functions useful to using and manipulating times. The most powerful function is
||Implements a busy wait sleep as well as an assert function for testing.|
- implement better unit tests
- migrate some capabilities to openhab-js (
rulesUtils.runRule and most of timeUtilshave already been migrated)
- migrate the rule templates to JS Scripting
build a script to build the rule templates so I don’t have to manually include library stuff in the template or require users to npm install the library (yet, I may require this eventually).I’m going to require installation of the
npmmodule going foreard.
Most of the capabilities have their own test script in the
test folder. This was written as a UI Script (Settings → Scripts) and throw errors when loaded by OH so I’ve removed the
.js extension to prevent them from loading (there is a recent PR that I think makes this no longer necessary).
Because of the one thread per script limitation, despite the efforts I’ve taken to avoid it, you will sometimes see
java.lang.IllegalStateException: Multi threaded access requested by thread Thread[OH-scheduler-26,5,main] but is not allowed for language(s) js.
That’s just a timing issue where two Timers tried to run at the same time. If it persists, you’ll have to adjust the times in the tests to avoid the overlap. I’m making some effort to eliminate these errors by adding code to stagger timers that are scheduled too close together. But I won’t do that until I migrate the rule templates because it depends on the
You will notice a separate
rule_templates folder. For now at least, I don’t want to keep my templates separate from the library so you can see the raw templates in that folder. However, these can only be installed through the marketplace.
If you want to submit updates to the rule templates, here is where to do it.
I’ve created a branch in the repo
before-npm. This has the now deprecated Jython and Nashorn implementations. If a GraalVM Python becomes a part of OH I might resurrect the Python libraries. For now, JS Scripting is the only language I’m supporting. If you need access to the deprecated stuff, use that branch.
The latest and greatest is currently in the
main branch. I will periodically cut a release when there are important updates to the library.