openHAB JavaScript library releases

florian-h05 · February 5, 2023, 7:52pm

Dear community,

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

What’s new in 5.7.1 & 5.7.0 & 5.6.0

These releases add medianSince, medianUntil and medianBetween methods to the ItemPersistence class as well as provides offset and timeOnly event information for DateTimeTrigger.
Offset param support for DateTimeTrigger in JSRule and Rule Builder has been introduced and PersistedState and PersistedItem can now be logged to the console.

The Item class has received two new methods: sendIncreaseCommand and sendDecreaseCommand. Checkout the docs to learn more about them.

In addition to these enhancements, several bugs were fixed.

Please checkout the changelog: openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub

What‘s new in 5.5.0

This minor release makes the message param of the notification builder optional (as it is not needed for hiding/removing a notification), adds support to JSRule for creating rules without triggers.
It also included a few minor fixes for rule builder‘s type definitions.

See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub for full changelog.

What’s new in 5.4.0

The 5.4.0 minor release adds support for adding multiple user IDs add once to the notification builder by passing multiple arguments to the addUserId method.
This release also includes a bugfix for openHAB 4.3, where the timer identifier was missing for UI scripts and rules.
Internal code improvements and fixed have led to the removal of the utils.isJsInstanceOfJavaType method, use JavaScript’s instanceof operator instead.

See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub for full changelog.

What’s new in 5.3.3 (5.3.2)

This patch release contains a number of bug fixes, including a fix for the SwitchableJSRule where the previous state for the Switch Item was not restored anymore and many JSDoc/type declaration fixes.

See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub for the full changelog.

What‘s new in 5.3.1 (5.3.0)

With this release, the notification builder was added to the actions namespace to support the upcoming notification enhancements.
In addition to that, a number of actions were marked as deprecated, because better, pure JS APIs with the same functionality are available.

See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub for the full changelog.

What‘s new in 5.2.0

This minor version adds the lastChange and nextChange to the ItemPersistence class.

See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub for the full changelog.

What’s new in 5.1.0

This new minor version adds two new features and fixes some nasty bugs, including:

The original input can now be accessed for file-bases rules using the .raw property of the event object.
ItemPersistence now supports for persisting TimeSeries and fixes a multi-threading related bug when persisting Item states.
The comparison in the sendCommandIfDifferent method of the Item has been fixed to correctly compare Quantities.

See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub for the full changelog.

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/CHANGELOG.md at main · openhab/openhab-js · GitHub.

What’s new in 4.x.x

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.

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

See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub.

4.8.0

The CoreUtil actions are now exported from the actions namespace.

See openhab-js/CHANGELOG.md at main · openhab/openhab-js · GitHub.

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.

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.

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.

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.

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.

4.2.1 (4.2.0)

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.

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.

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

stefan.hoehn · February 5, 2023, 9:12pm

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

rlkoshak · February 6, 2023, 2:35pm

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!

florian-h05 · February 6, 2023, 3:08pm

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.

rlkoshak · February 6, 2023, 9:23pm

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.

florian-h05 · February 6, 2023, 9:35pm

Yes, it published before I wrote this post: https://www.npmjs.com/package/openhab.

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.

rlkoshak · February 6, 2023, 10:44pm

npm upgrade didn’t work (and I think just wiped out something I was working on 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.

michaeljoos · February 7, 2023, 9:21am

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

Did I miss something or a bug?

florian-h05 · February 7, 2023, 12:16pm

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…

michaeljoos · February 7, 2023, 12:38pm

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

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

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

florian-h05 · February 7, 2023, 12:42pm

It returns a string as the docs say.

florian-h05 · February 23, 2023, 11:18am

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

florian-h05 · April 6, 2023, 7:29am

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.

polychronov · May 4, 2023, 1:22pm

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"/>
        </Logger>

Cheers,
Konstantin

rlkoshak · May 4, 2023, 3:25pm

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

console.log(console.loggerName);

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.

florian-h05 · May 5, 2023, 7:16am

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

polychronov · May 5, 2023, 7:53am

Hi.
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,
Konstantin

florian-h05 · May 13, 2023, 10:32am

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/CHANGELOG.md at v4.3.0 · openhab/openhab-js · GitHub for the changes.

florian-h05 · June 20, 2023, 12:56pm

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/CHANGELOG.md at main · openhab/openhab-js · GitHub.

rlkoshak · June 20, 2023, 1:06pm

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?