openHAB JavaScript library releases

Dear community,

we have just released a new version of the openHAB JavaScript library: version 4.1.0 :partying_face:
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:;

You can find the CHANGELOG at the openhab-js repo: openhab-js/ 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/ 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?

// 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 a Quantity object
  • 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

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:

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.


  • 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.

/cc @rlkoshak @digitaldan @stefan.hoehn @JustinG @maniac103


Thanks, Florian, for putting trillions of hours of dedication into that. :superhero:


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.

Do we know which snapshot build of 4.0 this will arrive in? At least for not I like to track with the version in the add-on so that I’m seeing what the default user will see.

Thanks to all for all the great work!

1 Like

Thanks for the suggestion, I’ve added it to the post.

I will open a PR to the addon to update the included version, it will be in the next SNAPSHOT after the PR has been merged.

1 Like

Has this been published to NPM yet? I just installed it and got 3.2.4. I tried to upgrade it and it said it’s already up to date.

Yes, it published before I wrote this post:

I guess the problem is that npm reads the package.json in the automation/js directory (this is always created when you run npm install) and when you now run npm install, it installs the latest version that matches the one in the package json. New major versions are not installed by npm because of semver. You can try npm update openhab or you edit the package.json and remove the openhab entry from it, then run npm install openhab again.

npm upgrade didn’t work (and I think just wiped out something I was working on :scream: I need to be more careful, thankfully I still had vim open).

I know I’ve upgraded before like this. I’m not sure why it’s not just working.

Looking at package-lock.json and it is locked to 3.4.2. package.json lists ^3.2.4 so of course it’s going to stick to 3.x.x. But an npm remove followed by an npm install openhab did the trick.

Surely there’s got to be a way to set it so I can upgrade without needing to install. Something to research later.

1 Like

I have updated via openhabian to this latest version.
For item.history.latestState() I only get this:


Did I miss something or a bug?

Can you please post the code of the actual call of this method?
What are the next lines of the log?

However given Rich‘s problems with the upgrade, I am not sure if the openhab-js upgrade logic is actually working…

OK, now I see that with this code I get an output:

var PVEnergyMeter = items.PV_Energy_Meter;
console.error( PVEnergyMeter.history.latestState().numericState );

Does item.history.latestState() return a ItemHistory-Object instead of a String?


It returns a string as the docs say.

We have just released a new minor version: 4.1.0.
Have a look at the first post of this topic for more details.