openhab/openhab-distro 4.0.0

openHAB 4.0.0

on GitHub

This is the official release of openHAB 4.0.0.

The binaries are available on our download page and via "Stable" on our APT repository.

New and Noteworthy

The openHAB 4.0 release is a feature release that contains many new features, enhancements and bug fixes, both for the core runtime and for many add-ons. You can find the most relevant ones listed in detail below.

openHAB 4.0 is backward compatible to openHAB 3.x setups - there are only a few exceptions where manual action is required to adapt an existing setup, so please carefully check the section on breaking changes.

Quick links:

• Notes about new add-ons
• Notes about the core runtime
• Notes about the UIs
• Notes about the add-ons
• Upgrade Process for openHABian, APT, RPM, Manual Installations
• Breaking Changes that require manual interaction after the upgrade.

Relevant Changes

New Add-ons

The following add-ons are newly introduced:

The following improvements were made:

Runtime

User Interfaces

Add-ons

Upgrade Process

Backup your configuration

If you are on openHABian, sudo openhabian-config menu option 50 will do for you,
else use sudo openhab-cli backup. Get the resulting file from $OPENHAB_USERDATA/backups, $OPENHAB_USERDATA is accessible as a Samba share. Using SSH it is /var/lib/openhab/ on your system.

If you run a Raspberry, get another SD card (an "Endurance" labelled one) and create a mirror copy.
openhabian-config menu option 54 will do for you on the live system, else there's tools such as dd or WinDiskImager.
Should you ever need to revert to your old openHAB system or to redo the upgrade process, simply change SD cards and start over from where you had started.

openHABian

If you are working with an openHABian setup,

1. Use SSH to connect to the command line and run sudo openhabian-config.
2. When being asked, answer that you want to update openHABian (note that’s not about openHAB itself).
3. If needed check which version you run via menu option 00.
4. If on Raspberry, create an image copy of your SD card using menu option 54.
5. Switching to openHAB 4.0.0 release depends on what version you’re upgrading from:
   
   a) If you have been running a 3.x release version, select menu entry 03 “Install or upgrade to latest openHAB” option.
   
   b) If you have been running a snapshot or milestone release of 4.0, select the first entry in menu option 41 (“Release”).

Package-based Installations

APT (Debian / Ubuntu and derivatives)

Make sure that openHAB is sourced from the latest location, has the correct GPG signing key and that your system can download .deb packages via HTTPS by following the instructions for a stable installation in the docs.

Please specifically note that the "old" signing key expired on July 24, 2023 - if you are still using this, you will need to download the latest key. See https://community.openhab.org/t/linux-repo-public-key-is-expiring-soon/147905 for details.

If the above is correct, simply upgrade by using:

sudo apt-get update
sudo apt-get upgrade

Alternatively, you can force apt to install 4.0.0 and its optional add-ons with:

sudo apt-get install openhab=4.0.0-1

## optional add-ons for offline installation ##
sudo apt-get install openhab-addons=4.0.0-1

RPM

openHAB is also distributed in RPM packages. To use them, make sure that openHAB is sourced from the latest location, and has the correct GPG signing key for verification by following the stable installation instructions outlined in the docs.

If the above is correct, then simply upgrade using your systems package manager (yum, dnf, etc.)

sudo yum update

Alternatively, you can force apt to install 4.0.0 and its optional add-ons with:

sudo yum install openhab-4.0.0-1

## optional addons for offline installation ##
sudo yum install openhab-addons-4.0.0-1

Manual Installations

Official update scripts are available that let you update your 3.x installation to version 4.0:

Linux/macOS

1. Change to your openHAB root directory (e.g. cd /opt/openhab)
2. Create a backup by calling sudo ./runtime/bin/backup.
3. Run the update command:

sudo ./runtime/bin/update 4.0.0

Windows

1. Make a backup of your openHAB installation folder.
2. Run PowerShell as administrator and change to your openHAB root directory (e.g. cd C:\openHAB)
3. Run the update command:

. .\runtime\bin\update.ps1
Update-openHAB -OHVersion 4.0.0

Breaking Changes that Require Manual Interaction after the Upgrade

Please read the following information carefully BEFORE starting the upgrade, since you might have to do some manual steps upfront.

Changes in Units of Measurement (UoM)

Units of Measurement is used for handling values with units attached (like 23 °C).
It has been refactored in openHAB 4 and needs some special attention when upgrading.
Since the introduction of UoM in openHAB 2.3 some limitations have been discovered.
One of these issues is inconsistent handling of units when no state description for the item is defined.
With openHAB 3.4 we already introduced a "default unit" that is used as the item's unit when no other units has been set.
Unfortunately this still has issues, e.g. it invalidates your persisted data when you change the unit that is used for displaying.

The new concept

The new concept follows these principles:

1. A Number item never shows a unit.
   Linking thing channels to such an item results in the unit being dropped (i.e. if the thing sends 23 °C), the item state will be 23.

2. An item with dimension (Number:Power) has a unit (e.g. kW that is used within openHAB that is independent from the unit that is used for displaying.
   A value that has no unit attached will be considered to be in that unit (i.e. 5 will result in the item state changing to 5 kW).
   Values with units will be converted to that unit (i.e. 500 W will result in an item state of 0.5 kW).
   Incompatible values (e.g. sending 5 Hz to a Number:Temperature channel) are discarded.

3. The unit of the item is used internally, in events and also for persistence.

4. The DISPLAY of the item is controlled by the state description.
   A unit set in the state description MUST be compatible to the unit of the item.
   The state description does not affect anything except displaying the values.

As a result your configuration might need some adjustments.
It is strongly recommended to check if something needs to be done BEFORE upgrading.

Upgrading

Textual configuration

For textual configuration (.items files), you should check all Number:.... items:

• If you see a unit in Main UI that is the same as the system default (https://www.openhab.org/docs/concepts/units-of-measurement.html#quantitytype), technically no change is needed.
  However it is strongly recommended to set unit metadata (see below).
• If you have set a state description and the unit is different from the system default (please be aware that this can also be the result of an automatic state description from a linked channel) you are required to set unit metadata.
  Failing to do so, will result in corrupted data in your persisted data.

Example:

Number:Energy Electrical_Consumption "Electrical Consumption [%.0f Wh]" { channel="myenergybinding:meterthing:totalmeter" }

needs adjustment, because the system default for Number:Energy is different (kWh).
Set the unit metadata to Wh.

Number:Energy Electrical_Consumption "Electrical Consumption [%.0f Wh]" { unit="Wh", channel="myenergybinding:meterthing:totalmeter" }

Another example:

Number:Dimensionless Relative_Humidity "Relative Humidity" { channel="myweatherbinding:hygrometerthing:humidity" }

might need adjustment when channel is of type system.atmospheric-humidity because it has state description "%.0f %%" and system default is "Abstract unit one (one)". Set the unit metadata to %:

Number:Dimensionless Relative_Humidity "Relative Humidity" { unit="%", channel="myweatherbinding:hygrometerthing:humidity" }

Managed configuration (UI)

An upgradetool was added to the update scripts.
This tool re-writes the item database and copies the state description units to the required metadata.
State descriptions from system-channel types are also automatically converted.
Have a close look at the output of the script during the upgrade process and check if you need to adjust some items manually.

Upgrading from openHAB versions <3.4

Older openHAB versions (before 3.4) had no system default unit for a lot of dimensions.
If you upgrade from such a version, it is recommended to set the unit metadata to those that you see in UI.

Changes in JavaScript Automation

The application/javascript MIME type has moved from NashornJS to GraalJS due to the removal of NashornJS in Java 14.
All UI-based JavaScript scripts including Blocklies are broken now. To make them work again:

• Migrate your Blocklies (see Rules Blockly | openHAB)
• Install the JavaScript Nashorn add-on and change the MIME type of your old application/javascript scripts to application/javascript;version=ECMAScript-5.1. The UI has a picker for the MIME type of existing scripts inside the "Script Details" menu inside the script editor. (Or rewrite them for GraalJS, where the openhab-js library will ease your life.)

Core Changes

• core.GenericEventTrigger and core.GenericEventCondition parameters have have changed. See https://www.openhab.org/docs/configuration/rules-ng.html#system-module-types.
• Rules are now triggered by ItemStateUpdatedEvent instead of ItemStateEvent. If you use JSR223 scripting without helper libraries and expect a certain Java type, code changes might be needed.
• The syntax for an item category/icon in a textual configuration file no longer accepts a value enclosed in quotes. So <temperature> is valid but not <"temperature">. Please update the definition of your items if necessary.
• SCRIPT transformation has been removed and replaced with language-specific transformations: JS, RB, PY, DSL, GROOVY, etc. See https://www.openhab.org/docs/configuration/transformations.html#script-transformation

Changes in Add-ons

Airthings Binding

• The channels radon_st_avg and radon_lt_avg are now of dimension RadiationSpecificActivity instead of Density. Please update your linked items accordingly.

Bosch Indego Binding

• Due to changes in the cloud services, the authentication method has changed. Please follow the authorization flow described in the documentation. Furthermore, a bridge is now required and must be assigned to the indego thing. Configuration of username and password is no longer required/supported.

ComfoAir Binding

• The channel enthalpy#enthalpyTime now represents the set time (in minutes) instead of the internal number value that is sent to the device (minutes / 12).

DanfossAirUnit Binding

• The deprecated channel 'manual_fan_speed' has been removed. Please use channel 'manual_fan_step' introduced in 3.2.

Dark Sky Binding

• Due to EOL of their API, this add-on has been removed.

Generac MobileLink Binding

• Due to an API change, existing Generator Things will need to be deleted and added again. Additionally, existing Items will need to be adjusted to reflect the updated Generator Thing channels.

HomeKit

• Add-on wide configuration of mappings for thermostat modes is no longer supported. Please use item-level configuration as described in the README.

Hue emulation

• The uniqueid value has been changed to resolve discovery issues with Alexa. You may need to rediscover "devices" in all services that use the hue emulation (Amazon Echo, Logitech Harmony, etc).

Hunter Douglas (Luxaflex) PowerView Binding

• Deprecated scene channels have been removed. Please use the scene channels introduced in 3.2 (in channel group 'scenes').

JavaScript

• JavaScript engines have changed their MIME types: NashornJS is application/javascript:version=ECMAScript-5.1 and GraalJS is application/javascript. Please update your scripts to either make them compatible with GraalJS or change the MIME type to continue to use NashornJS. For Blockly migration, visit the Blockly documentation.

JavaScript NashornJS

• NashornJS has been removed from core and isn't included by default. If you still need or want to use it, you can install it as an add-on.

JavaScript Scripting Automation

• The old "metadata" and "itemchannellink" APIs have been replaced by a new API with extended functionality on the "items" namespace.
• ItemHistory: historicState, maximumBetween, maximumSince, minimumBetween, minimumSince & previousState now return a HistoricItem instead of just the state. previousStateTimestamp has been removed, the timestamp is available on the HistoricItem.

KNX Binding

• Units of Measurements have been introduced, make sure you use correct units in the state description. Rules may need to be adapted. Several items changed from PercentType to QuantityType, i.e. raw values increase by a factor of 100.

LuftdatenInfo Binding

• The binding was renamed to Sensor.Community Binding to match the new naming of the service. Things need to be recreated.

Netatmo Binding

• Due to API authorization process change scheduled on the 2023/04/17 - refresh Token is no more stored in thing configuration, thus can be removed from things config files. If it remains, it'll be ignored.
• New scope has been added for the introduction of the Carbon Monoxide Alarm. Authorization process has to be replayed (and former refreshToken can be removed from things config files -- see above).

Windcentrale Binding

• The binding has been reworked to support the new API that requires authentication. Delete old 'mill' Things, add an 'account' Bridge and add new 'windmill' Things using the 'account' as Bridge. The channel names now follow the naming conventions. Items must be adapted for these changes.