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.
As usual, you can upgrade through openhabian-config or by running npm update.
Releases
v2.0.3
Depends on openhab-js 4.5.1.
Library
- Updated code with new OH 4 concepts and openhab-js features
- Added warning level logs to all deprecated functions and features
- Added a factory function for all classes. Now instead of the old way to import and instantiate:
var { gatekeeper } = require('openhab_rules_tools');
var gk = new gatekeeper.Gatekeeper();
use
var { Gatekeeper } = require('openhab_rules_tools');
var gk = Gatekeeper();
A warning log message occurs if you attempt to import the class instead of using the factory.
- [testUtils.sleep] Reimplemented to use
java.lang.Thread.sleep()instead of a busy wait.
Rule Templates
- Rewritten all but one of the rule templates for OH 4 using JS Scripting instead of Nashorn (one rule template left to update is Meter Reading)
- Greatly improved error checking and configuration checking so problems result in meaningful and actionably error messages across all rule templates
- All my rule templates now depend on openhab_rules_tools being installed and available
- Added library version checking to all rule templates, an error will occur if too old of a version of a library is detected
Deprecated
- [To Today] Deprecated with no plans to migrate, use the new
Time is <item> timeOnlyrule trigger - [MQTT Online Status] Deprecated, this feature is now built into the binding. See your MQTT Broker Thing config.
Merged Tempaltes
- [MQTT Event Bus Publication/Subscription] Merged into a new consolidated rule template
- [Open Reminder and Threshold Alert] Merged into a new consolidated rule template which additionally supports hysteresis, overriding properties on a per Item basis, and calling an alert rule when the Item first changes to an alerting state, in addition to alerting when it’s been in the alerting state for a time and when it exits the alerting state.
New
- [Delay Start] A new template that runs at system runlevel 40 and disables the configured rules. It then waits until system runlevel 100 plus a configurable delay to reenable them
- [Restart Expire] On OH startup, restart Items configured with
expireby posting their current state as an update. - [Expire Updater] A script that can be called from another rule or a MainUI Widget to replace the
expireconfiguration with a new one.
Changed Behavior
- [Thing Status Reporting] Now triggers immediately on the Thing status events instead of polling. As a result it calls the processing rule only with the information about the one Thing that changed status.
- [Debounce] Triggering the rule manually will check the config and report errors
- [Time Based State Machine] Running the rule manually will cause more information to be logged about configuration checking. The date portion of the date times are ignored.
v2.0.2
Fixed a bug in loopingTimer
v2.0.1
Fixed a bug in the version checking logic in helpers.
v2.0.0
This is the first release that fully requires OH 4.0 and depends on openhab-js 4.1 or later. This update fixes a couple of long standing bugs as well as some additions.
All my rule templates going forward will check the versions of this and openhab-js and throw an exception if one is too old to run the rule.
Library
- Readme updates by @rkoshak in #79
- [countdownTimer] Call the function at the end, not the beginning by @rkoshak in #86
- [loopingTimer] throw exception when looping timer time in past by @rkoshak in #87
- [helpers] Added helper functions to test library version nums by @rkoshak in #89
Rule Templates
Note: Rule templates do not follow a release cycle. As soon as they are merged they become available on the marketplace.
- [time_state_machine] Added code to calculate and publish the current state by @rkoshak in #80
- [mqttEb] Initial reimplementation of MQTT Event Bus by @rkoshak in #81
- [expire_updater] Added expire_updater rule template by @rkoshak in #82
- [thingStatus] Changed trigger for thingStatus to support changes in core by @rkoshak in #83
- [presenceSim] Reimplementation of Presence simulation for OH 4 by @rkoshak in #84
- [rule tempaltes] Don’t set log level in rule template by @rkoshak in #85
- [mqttEb] Publishing ONLINE is now handled by the Broker Thing by @rkoshak in #88
v 1.2.0
- Use
createTimerinstead ofcreateTimerWithArgumentby @florian-h05 in #76 - Added rewrite of the Thing Status Reporting rule template using ECMAScript 2021 for OH 4 by @rkoshak in #77
- Added rewrite of the Debounce rule template using ECMAScript 2021 for OH 4 by @rkoshak (I forgot to make a PR and merged straight into main)
- Added rewrite of the Time Based State Machine using ECMAScript 2021 for OH 4 by @rkoshak (I forgot to make a PR and merged straight into main)
- Added checkGrpAndMetadata to helpers.js and exposed it to be used by rule templates to validate Item configs for rule templates like Debounce and Time Based State Machine by @rkoshak (I forgot to make a PR and merged straight into main)
As of this release the library depends on openhab-js 4.0 or later.
v1.1.4
Added the ability to supply a name when creating a timer to make debugging easier. If the name isn’t supplied, the ruleUID will be used. If that isn’t available the filename will be used. Otherwise the name defaults to the name of the library.
Note: v1.1.3 was a mistake and ended up getting out of sync with npm.
v1.1.2
- Deprecated
timeUtils.toDateTime()in favor of openhab-js’time.toZDT(). There are minor differences in how that library handles Duration strings. It now follows the ISO8601 standard.
v1.1.1
- Minor bug fixes in timeUtils
- Added .npmignore to avoid publishing rule templates as part of the npm package
v1.1.0
Initial full release rewritten for the JS Scripting ECMAScript 2021 using the openhab-js library.
History
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.
I use this same repo as the location for my rule templates.
Installation
Dependencies
This library has a dependency on the openhab-js library. If you want the latest version of openhab-js library it can be installed through openhabian-config menu option 46 | Install openhab-js or by navigating to the $OH_CONF/automation/js folder and running npm install openhab.
For now the library assumes that the settings for JS Scripting are at the default settings which causes openhab-js to automatically be injected into your rules. If you turn that feature off, some of the classes and functions in the library may not work. Please report if this is the case so I can update that. I’d like it to work as is in both cases.
See the release notes above for the latest version of openhab-js that openhab_rules_tools depends upon.
openHABian
The library is now installed and updated by default in openHABian. So if you are running the latest openHABian, you’ve already got it. You can verify this by looking in $OH_CONF/automation/js/node_modules and if there is an openhab_rules_tools folder you are good. If not, update your openHABian and navigate to menu option 47 | Install openhab_rules_tools.
However, as of this writing (2/23/2023) oepnHABian will not upgrade to a new major version number. This works to our advantage as now that version 2.0.1 depends on OH 4, upgrading won’t break your system. When you upgrade to OH 4, uninstall and reinstall and you’ll get the latest 2.X version.
Linux
From the $OH_CONF/automation/js folder run
sudo -u openhab npm i openhab_rules_tools
Look up instructions for running npm on your specific OS if not running on Linux.
To move to a new major version (e.g. v1.2.0 to v2.0.1), remove and then install again.
Docs
Lacking at the moment. Look at the files under tests for examples and the code itself for usage details or ask questions below or on GitHiub.
Implemented Capabilities
| Name | What it does |
|---|---|
CountdownTimer |
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. |
Deferred |
Class that allows one to schedule a command or update to an Item in the future. |
Gatekeeper |
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). |
groupUtils |
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. |
LoopingTimer |
Implements a Timer that keeps calling a function as long as that function doesn’t return null. When the loop should continue, the function must return a when (see timeUtils). |
RateLimit |
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). |
rulesUtils |
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. |
TimerMgr |
Implements all the book keeping required when managing multiple timers in one rule (e.g. one per Item). |
timeUtils |
Mostly Deprecated: most of this functionality is now part of openhab-js. A couple of functions useful to using and manipulating times. |
testUtils |
Implements sleep (wrapper around Thread.sleep() as well as an assert function for testing. |
helpers |
Mostly functions useful internal to the library or by us in rule templates and not of general interest. To get the current version of openhab_rules_tools use helpers.OHRT_VERSION |
To Do
- docs
- 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
Testing
Most of the capabilities have their own test script in the test folder. These are written as a UI Script (Settings → Scripts). It’s still a todo to migrate to a true unit test framework. These are not part of the node module.
Rule Templates
You will notice a separate rule_templates folder on GitHub. These can only be installed through the marketplace and they are excluded from the node module.
If you want to submit updates to the rule templates, here is where to do it.
