Dear community,
we have just released a new version of the openHAB JavaScript library: version 4.1.0 
Big thanks to everyone who was involved in this new release!
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 aQuantityobject -
numericState: 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: https://github.com/openhab/openhab-webui/pull/1664.
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).
