openHAB JavaScript library releases

Dear community,

we have just released a new version of the openHAB JavaScript library: version 5.0.0 :partying_face:

What‘s new in 5.0.0

This new major version brings several BREAKING CHANGES and drops support for openHAB 4.1.x or older - openHAB 4.2.0 (not yet released) is the new minimum requirement.

In case any major bugs are discovered in the 4.9.0 release, a patch release may be published.

Minor Breaking Changes

  • File-based Event Object: Remove deprecated state property - use receivedState instead.
  • File-based Event Object: Remove deprecated receivedTrigger property - use receivedEvent instead.
  • cache: Remove the deprecated default cache, i.e. remove cache.get(…), cache.put(…), cache.remove(…) and cache.exists(…) - use the private or shared cache instead.
  • actions.ScriptExecution: Remove deprecated method createTimerWithArgument - use createTimer or setTimeout instead and pass the argument as parameter to the callback.

Major Breaking Change: Rewrite of the Item Persistence API

Due to breaking changes at openHAB Core, the Item History API has been replaced with the new Item Persistence API, which provides additional functionality wrt changed return types and support for future states.

Blockly users need to search their rules/scripts for the query .history using the developer sidebar search (click Shift + Alt + D), open each rule/script and click save - Blockly will automatically generate the right code.

All other JS Scripting users have to manually migrate their rules/scripts.
To find all usages of the Item history API, use the developer sidebar search as described for Blockly.

Then replace all usages of .history of .persistence and adjust the usage of these methods:

  • averageSince, averageBetween
    , deltaSince, deltaBetween, deviationSince, deviationBetween, sumSince, sumBetween, varianceSince, varianceBetween:
    These methods now return a PersistedState instead of a number - use the numericState property to get the numeric state as before.
  • historicState: Replace with persistedState.
  • Remove latestState method - instead access the Item state directly.
  • Remove deprecated evolutionRate method - use evolutionRateSince instead.

Read the docs to learn about the full functionality of the new API.

Also see openhab-js/ at main · openhab/openhab-js · GitHub.

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.

Remove the Item suffix from the type property of the items.Item class.

See openhab-js/ 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/ 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) {

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/ 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/ 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/ 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/ 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/ 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/ 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:;

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


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

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.

About one month passed by, and we have a new version: 4.2.1!
Have a look at the first post of this topic for more details.

Hi all,
recently I have migrated to 4.0.0-M2. For some reason the logs of my JS rules do not show up in the respective files like before. Was there any change (maybe namespace/package) in this regard?
I used the following in my log4j.xml before:
org.openhab.automation.script.file.<then the filename of my .js rule>

For ex.

<Logger additivity="false" level="DEBUG" name="org.openhab.automation.script.file.electricity.rule.js">
			<AppenderRef ref="ELECTRICITY_SCRIPT"/>


I know by default UI rules are in the org.openhab.automation.script.ui.namespace by default. I've never used file based rules in JS Scripting but.file.` makes sense.

I know of no changes to the namespace.

You can test to see by setting the logger name yourself using

console.loggerName = '<what ever you want>';

You can log out the name of the logger using


But of course if the logs for that rule are being suppressed for some reason that doesn’t help you much.

You can set the logging level of the rule in the rule itself using

osgi.getService('org.apache.karaf.log.core.LogService').setLevel(console.loggerName, 'DEBUG');

That will add a new entry to log4j2.xml and you can see the logger name there.

Can you please check if there is an ELECTRICITY_SCRIPT appender in the Appenders section?

Sorry very much for my hasty post.
I’ve put additional logs in some rules and it seems that the issue is not in the logging but rather in the binding that I’m replacing currently with a version that I develop.
I can confirm now that the namespaces have not changed and the logging works like in a 3.4.x.

Sorry for the confusion!

Best regards,

1 Like

A new month, a new release: Version 4.3.0 is out now!

It bring a bugfix for the ItemSemantics and minor improvements for Item.quantitiyState.
See openhab-js/ at v4.3.0 · openhab/openhab-js · GitHub for the changes.

1 Like

As usual, a new month, a new relase: Version 4.4.0 has been published a few minutes ago!

It bring several bugfixes and enhancements, just have a look at my original post or the changelog openhab-js/ at main · openhab/openhab-js · GitHub.

1 Like

What’s the usual timeline between a new release and when it becomes part of the add-on? It’s obvious for milestones and release but not as obvious for snapshots.

When you announce it here will it be available in the next snapshot or is there some lag?