Ivan’s Updates to the Helper Libraries
I have decided to start maintaining my own fork of the openHAB Helper Libraries, at least for the time being, in light of the lack of activity in the original repo. There has been growing demand for OH3 support among other things, and I wanted to make that available in one place. In the event that the original maintainer returns, I will work with him to get these changes merged into the original repo.
I will be maintaining a change log detailing what has been done in my fork for reference.
Currently I have not updated the documentation to reflect any of the additions that have been made, I will get to that as soon as possible (any help is appreciated).
Where to get them
You can find my fork on GitHub in the Ivan’s Updates branch, which I have made the default in my repo.
Please use this branch when submitting any PRs, and mind that you make your PR against that branch on GitHub as it will default to the original repo.
Installation
Python
-
openHAB 2.x - Follow the instructions here.
- Step 7 - Download the contents of this repository.
-
openHAB 3.x - Follow the above instructions with the following exceptions:
- Step 5 - Install the Jython Scripting add-on.
- Step 7 - Download the contents of this repository.
- Step 10 & 11 - skip these steps.
JavaScript (ES5)
Currently this is a work in progress to match the Python functionality
-
openHAB 2.x - Follow the instructions here.
- Step 7 - Download the contents of this repository.
-
openHAB 3.x - Follow instructions with the following exceptions:
- Step 5 - skip this step.
- Step 7 - Download the contents of this repository.
What’s New
Below you will find highlights for things that have been added or updated in each language.
Python
- Added openHAB 3.x compatibility.
- Added custom logger class that provides
TRACElevel logging. - Added a simplified getLogger function that will automatically prepend the
LOG_PREFIX.from core.log import getLogger log = getLogger("mylib.log") # will log to '{LOG_PREFIX}.mylib.log' - Generic Event Triggers are now fixed (OH2 + 3) so you can use Item added/removed/modified triggers as well as Thing Status triggers.
- Date conversion functions can now accept a DateTime Item and will extract its state.
Python Type Hints!
Typing files are now available in this repo for openHAB 3. Stubs for the Helper Libraries will be added to that repo soon are now available in my Helper Libraries repo in Core/typings.
What this means is you will now have property and method hints right in your IDE when writing rules! No longer will you always need to have the documentation open or dig around in the openHAB code just to find methods of Java objects. The repo contains instructions on installing them and setting up your IDE, along with some examples to get you started.
JavaScript (ES5)
I have done a fair bit of work on getting the JavaScript libraries up to par with the Jython ones. While this is still incomplete, I have published my work so far in a PR for anyone interested in testing them or helping complete the work. Details are in the PR about what is left to do.
- Port Jython libraries into JavaScript.
- Added openHAB 3.x compatibility.
- Generic Event Triggers are now fixed (OH2 + 3) so you can use Item added/removed/modified triggers as well as Thing Status triggers.
New JS Rule Syntax
ECMAScript 5 has no concept of decorators, unlike Python, so the use of the rule and when functions looks a little different but works the same. Below is a rule I made in JS that queries my devices running Tasmota for their state when they come online. The rule and when functions work in the exact same way as they do in Python, so refer to the Python documentation but use them like this.
New Style Javascript Rule Example
var OPENHAB_CONF = Java.type("java.lang.System").getProperty("openhab.conf");
var JS_PATH = OPENHAB_CONF + "/automation/lib/javascript";
load(JS_PATH + "/core/rules.js");
load(JS_PATH + "/core/triggers.js");
load(JS_PATH + "/core/metadata.js");
load(JS_PATH + "/core/log.js");
var LOG = getLogger(LOG_PREFIX + ".tasmota");
var TOPICS = [
"POWER",
"SWITCH"
]
var mqtt = actions.get("mqtt", "mqtt:broker:alfred");
function tasmota_online(event) {
if (event.itemState === ON) {
LOG.debug(
"Polling device '{}'",
event.itemName
)
var device_topic = get_value(event.itemName, "topic");
if (device_topic) {
TOPICS.forEach(function(topic) {
for (var i = 0; i < 9; i++) {
mqtt.publishMQTT(device_topic + "/cmnd/" + topic + (i > 0 ? i : ""), "");
}
});
}
}
}
when("Descendent of equipment_status_tasmota changed")(tasmota_online);
rule(
"Tasmota Device Online Query",
"Queries Tasmota devices for relay, switch, etc states when they come online."
)(tasmota_online);
