Dear community,
we have just released a new version of the openHAB JavaScript library: version 4.9.0 
Big thanks to everyone who was involved in this new release!
What’s new in 4.9.0
The JS-Joda date & time library has been upgraded to the latest version and the compiled size of the openhab-js library has been reduced.
SwitchableJSRule now supports to set the name of the switch Item, which allows to use SwitchableJSRule with Items different from the automatically created Item.
See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub.
What’s new in 4.8.0
The CoreUtil actions are now exported from the actions namespace.
See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub.
What’s new in 4.7.0
The GenericEventTrigger for JSRule and getAllStatesBetween as well as getAllStatesSince for the Item history API have been added.
actions.ScriptExecution.createTimer has introduced support to pass parameters in the setTimeout style:
function myTimerFunc (arg1, arg2) {
console.log(arg1);
console.log(arg2);
}
actions.ScriptExecution.createTimer(time.toZDT().plusSeconds(10), myTimerFunc, 'Hello', 'openHAB');
Many, many bugfixes, including timezone fixes for toZDT and toZDT failure for some input types.
See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub.
What’s new in 4.6.0
This release fixes a bug where instance of Item checks were not working because webpack does not keep classnames. Classnames were used to check the class of an object where the instanceof operator couldn’t be used because it would introduce circular dependencies.
The bug caused time.toZDT to fail when passing an Item.
It also contains several enhancements:
Rule builder got the DateTime and the TimeOfDay triggers as well as the fromOn and fromOff Item trigger configs added, and we also improved the type definitions so IntelliSense should be better now.
For JSRule, we finally imp,emented event information for time-based and run-rule triggers and also manual runs. This is something that openHAB core already supports since openHAB 3.4.0.M4, but the support in the library was missing until this release.
As usual, you will find the changelog at the repo: openhab-js/CHANGELOG.md at v4.6.0 · openhab/openhab-js · GitHub.
What‘s new in 4.5.0
One enhancement to the Quantity API: The factory method and the divide/multiply methods now accept compatible Items.
For Number Items (without UoM), divide and multiply are applied without a unit, e.g. 5 kW / 2 = 2.5 kW. All other Items (Number UoM and String) are parsed to Quantity.
The changelog is available at the repo: openhab-js/CHANGELOG.md at v4.5.0 · openhab/openhab-js · GitHub.
What’s new in 4.4.0
We have two new utils methods: javaInstantToJsInstant and javaZDTToJsZDT. These are useful for times when you get raw Java data types and the library can’t help with automatic conversion, e.g. for Thing actions.
Also fixed is a nasty bug where SwitchableJSRule did not keep the disabled state of a rule after reloading the script file.
Furthermore, we fixed an issue where times.toZDT from a DateTime Item failed and updated the webpack configuration so that class and function names are kept when bundling the library. This should ease debugging when library issues occur.
Last but not least, the Thing.setX methods were fixed to persist changes to label, location or properties to the JSONDB so they survive an openHAB restart.
As usual, the CHANGELOG is available on the openhab-js repo: openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub.
What’s new in 4.3.0
This version brings bugfixes for the ItemSemantics where the location and equipment properties were not working and improves Item.quantityState to not return unit-less Quantities.
As usual, the CHANGELOG is available on the openhab-js repo: openhab-js/CHANGELOG.md at v4.3.0 · openhab/openhab-js · GitHub.
What‘s new in 4.2.0 & 4.2.1
This new versions again focus on bugfixes and include one enhancement:
The ItemSemantics (available via the semantics property of the Item) have been extended.
The bugfixes are mostly related to the Quantity, but the most important fix adjusts the event object to recent breaking changes in openHAB Core. Backward compatibility is fully kept.
You can find the CHANGELOG at the openhab-js repo: openhab-js/CHANGELOG.md at v4.2.1 · openhab/openhab-js · GitHub.
What‘s new in 4.1.0
This new version focuses on bugfixes (it fixes three bugs), but brings one new features as well:
Access to the version string of the openhab-js library directly from your script, which is useful for debugging and writing rule templates:
console.info(utils.OPENHAB_JS_VERSION);
You can find the CHANGELOG at the openhab-js repo: openhab-js/CHANGELOG.md at v4.1.0 · openhab/openhab-js · GitHub.
What‘s new in 4.0.0
Version 4.0.0 brings both breaking changes and great new features. I cannot talk about each and every change, but I will showcase the big things here.
You can find the CHANGELOG (as usual) on the openhab-js repo: openhab-js/CHANGELOG.md at v4.0.0 · openhab/openhab-js · GitHub.
Simplified Item Access
Have you ever wondered if there is a way to access your Items in a shorter way than always calling items.getItem('LivingRoom_Light')?
Well, there WAS no way, but no there it is: items.LivingRoom_Light.
It’s also possible to access Items using dict notation: items['LivingRoom_Light'].
This is useful in cases where you have to construct the name of the Item in a String variable.
It is now possible to perform Item lookup directly on the items namespace using the Item’s name.
Units of Measurement / Quantity Handling
Although this API is already part of the 3.2.x releases, I will talk about it here because it is finally finished with 4.0.0.
The new Quantity API introduces simple handling of quantities with unit conversion, comparison, mathematical operations and more. The following examples showcase it‘s power:
var bathroom_temp = items.Bathroom_Temp;
// Is it less then 20 °C in the bathroom?
if (bathroom_temp.quantityState.lessThan('20 °C')) console.log('It might be too cold to have a shower ...');
// What if you want to view your bathroom temperature in Fahrenheit?
console.log(bathroom_temp.quantityState.toUnit('°F'));
// Do you always struggle with length units? No problem ...
var qty = Quantity('5 m');
qty = qty.add('7.45 mi'); // add 7.45 miles to the 5 meters
I hope these examples give you an impression of what’s possible now.
For full docs, visit GitHub - openhab/openhab-js at v4.0.0.
For the Blockly users out there: UoM handling will come to Blockly as well!
You just have to be a bit more patient than the other JS users, it will come with openHAB 4 this summer. The PR is already merged: Blockly: Upgrade to v9, add JSScripting (GraalVM) implementations, UoM block types by stefan-hoehn · Pull Request #1617 · openhab/openhab-webui · GitHub.
New State Representations for Items
You might have already noticed it in the UoM examples:
Item has new state properties:
quantityState: represents the state as aQuantityobjectnumericState: the Item state as a float
Both of course only work for numeric Item states.
If they aren’t compatible with your Item, the will be null.
Visit GitHub - openhab/openhab-js at v4.0.0 for full docs.
More Data from Persistence
The maximum and minimum between and since methods, and the previousState method now return the new HistoricItem instead of just the state.
The HistoricItem gives you access to the state in various representations and the timestamp when that state was recorded.
Note that this is a breaking change.
For full docs, visit GitHub - openhab/openhab-js at v4.0.0.
Completely Renewed metadata API
For those who use metadata to store all types of information close to their Items:
We have completely refactored the metadata API!
It is now possible to create, edit and delete metadata, modify value and configuration of it and that with native JS types!
// Configure the corridor light to automatically turn off after 5m
items.metadata.replaceMetadata(items.Corridor_Lights, 'expire', '5m,command=OFF');
// Store some custom information in your blinds Item
items.metadata.replaceMetadata(items.Kitchen_Blinds, 'myMetadata', '', {
value1: 'Hello world',
someNumber: 464
});
// Set a new minimum value for your bedroom's thermostat
var meta = items.metadata.getMetadata(items.Bedroom_Thermostat, 'stateDescription');
meta.configuration.min = 15
items.metadata.replaceMetadata(items.Bedroom_Thermostat, 'stateDescription', meta.value, meta.configuration);
// View full metadata of an Item
console.log(items.metadata.getMetadata(items.MyItem));
Full API docs can be found at metadata - Documentation.
Again, for Blockly users this new functionality will also become available with new Blocks in openHAB 4: Blockly metadata blocks by stefan-hoehn · Pull Request #1664 · openhab/openhab-webui · GitHub.
Note that the old metadata API (that wasn‘t working well) has been replaced with this one, so this is a breaking change.
How to install?
On openHABian:
- Open the openHABian config tool:
sudo openhabian-config. - Select
40 | openHAB Related. - Select
46 | Install openhab-js.
Manually:
- Go to the JavaScript user scripts directory:
cd $OPENHAB_CONF/automation/js. - You may need to install
npm. - Install the latest release: Run
npm i openhab.
I need to be more careful, thankfully I still had vim open).
