openhab/openhab-distro 4.2.0

openHAB 4.2.0

on GitHub

This is the official release of openHAB 4.2.0.

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

New and Noteworthy

The openHAB 4.2 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.2 is backward compatible to openHAB 4.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:

Runtime

The following improvements were made to the core and the distro:

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.2.0 release depends on what version you’re upgrading from:
   
   a) If you have been running a 4.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.2, 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.

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.2.0 and its optional add-ons with:

sudo apt-get install openhab=4.2.0-1

## optional add-ons for offline installation ##
sudo apt-get install openhab-addons=4.2.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.2.0 and its optional add-ons with:

sudo yum install openhab-4.2.0-1

## optional add-ons for offline installation ##
sudo yum install openhab-addons-4.2.0-1

Manual Installations

Official update scripts are available that let you update your 4.x installation to version 4.2:

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

Breaking Changes that Require Manual Interaction after the Upgrade

Changes in Add-ons

AndroidTV Binding

• The thing configuration of 'port' has been renamed and split to 'googletvPort' and 'shieldtvPort'

Energi Data Service Binding

• Thing action calculatePrice now returns 'null' if price data is missing within the requested period. Rules may need to be adjusted.

evcc Binding

• Update to evcc API version 0.123.1 results in several new or updated channels. Existing Items will need to be adjusted.

ISM8 Binding

• Most channels have changed and are now using Units of Measurements. Items must be adapted and the things must be recreated.

JavaScript Scripting Automation

• The 'Item' suffix has been removed from Item.type, i.e. 'SwitchItem' becomes 'Switch'.
• The 'Item.history' API has been replaced by 'Item.persistence', which mostly provides the same functionality, but some return types changed and 'historicState' has been renamed to 'persistedState'. Blockly users should search for '.history' using the developer sidebar and re-save all scripts that contain this search query.
• Deprecated methods 'actions.ScriptExecution.createTimerWithArgument' (use 'createTimer'), 'cache.get', 'cache.put', 'cache.remove' & 'cache.exists' (use the private or shared cache) and fields 'state' (use 'receivedState') & 'receivedTrigger' (use 'receivedEvent') have been removed from the event object.

Please read the release community post to learn learn about adjusting your scripts & rules to the breaking changes.

Jython Scripting

• Default python lib path changed from "/automation/lib/python" to "/automation/jython/lib" and default python script path changed from "automation/jsr223" to "automation/jython". Just move your python scripts and libraries to new locations. The path "automation/jsr223" is still working, because it is used as a deprecated path for all automation add-ons.

MercedesMe Binding

• Public API from Mercedes was switched off. Now binding is using Smartphone API. Bridges and things cannot be reused and needs to be recreated with the updated binding.

OpenWeatherMap Binding

• One Call API version 2.5 is to be shut down in June 2024. Read the binding's documentation for the migration process.

Persistence Extensions

• "historicState" and evolutionRate" have been deprecated and replaced by "persistedState" and "evolutionRateSince". They will be removed in a future version. Methods may now return QuantityType instead of DecimalType. In Rules DSL, if you wish to do calculations without units, you may have to cast the results of the method to DecimalType explicitly. See documentation for details.

SMA Energy Meter

• The Thing configuration has changed and now also requires the parameter "serialNumber".

Transformations

• NULL and UNDEF item states are now passed to any defined transformation.

Transformations-MAP

• "-" entry defined in a MAP file is no more used by sitemap UIs when the item state is NULL or UNDEF. You can now define "NULL" and "UNDEF" entries to map these 2 particular states or rely as before on the definition of a default mapping to map anything that has no entry in your file including NULL and UNDEF.