openhab/openhab-distro 5.1.0

openHAB 5.1.0

on GitHub

This is the official release of openHAB 5.1.0.

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

New and Noteworthy

The openHAB 5.1 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.

Please also note our release blog post, which describes the major new features in depth.

openHAB 5.1 is backward compatible to openHAB 5.0 setups, though there are a few exceptions where manual action is required to adapt an existing setup, so please carefully check the section on breaking changes. It is especially important to know that openHAB 5.x requires Java 21, so in case you are coming from a 4.x installation and haven't yet upgraded, this is mandatory.

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,

check for compatibility

openHABian will refuse to install or upgrade to openHAB 5.1 when it detects a 32 bit operating system.
This is because openHAB needs Java 21 but as of today, there is no JVM 21 package available known to work on 32 bit ARM platforms.
Note: this is not about the processor type but about 32/64 bitness of the operating system.
There have been both types of openHABian images for Raspberries and many of you users will still be on the 32 bit OS.
Check the output of getconf LONG_BIT to see what you're on.

If you are on 64 bit, proceed to

upgrade

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 on Raspberry, it's optional but recommended to create an image copy of your SD card using menu option 54.
4. Switching to openHAB 5.0.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 5.0, select the first entry in menu option 41 (“Release”).

If you are still on 32 bit OS, you can stay with your current openHAB 4 setup or do the upgrade to 64 bit as described in the openHAB 5.0.0 Release Notes.

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

sudo apt-get install openhab=5.1.0-1

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

sudo yum install openhab-5.1.0-1

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

Manual Installations

Official update scripts are available that let you update your 5.0 installation to version 5.1:

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

Breaking Changes that Require Manual Interaction after the Upgrade

Changes in Core

• Persistence default strategies are removed and not applied automatically anymore. Managed persistence configurations are updated automatically. If you have a file based configuration with an existing .persist file, you may have to update your configuration: remove "default" from Strategies and make sure all Items definitions have a strategy defined.

Changes in Add-ons

AhaWasteCollection Binding

• A typo was corrected in the lightweight channel id, you may need to correct your configuration.

Allplay Binding

• Due to limited usage and increasing maintenance issues, this binding has been removed.

Automower Binding

• Restructured to modular things with auto-discovery of datapoints. New things and channels will need to be linked, existing items need to be adjusted.

evcc Binding

• Restructured to modular things with auto-discovery of datapoints. You must reconfigure settings, recreate Things, and adjust Items as previous configurations are incompatible.

Folderwatcher Binding

• A typo was corrected in the AzureBlob thing parameter containerPath. You may need to reconfigure this parameter.

Freebox Binding

• The binding has been removed from the distribution. You should consider migrating to the FreeboxOS binding.

Guntamatic Binding

• Channel ID spelling errors (such as 079-interuption-0 and 080-interuption-1) have been corrected. You may need to update items linked to these channels.

Home Assistant Binding

• The binding has been split from the main MQTT binding, and will not be auto-installed. If you use this binding, it will need to be manually re-installed. You may also need to re-configure the binding if discovery settings have been customized.

Homie Binding

• The binding has been split from the main MQTT binding, and will not be auto-installed. If you use this binding, it will need to be manually re-installed.

JavaScript Automation

• The event object in UI-based environments has been aligned with the file-based event object. Properties are now pure JavaScript types and property names have changed. Blockly users need to resave their scripts.
• Automatic injection of the openHAB JavaScript library now allows for more fine-grained control. It is recommended to manually import required namespaces from the openhab library in file-based scripts and transformations and disable automatic injection for file-based scripts and transformations.

KNX Binding

• Using secure tunnel or secure router with autodiscovered Gateway Things may cause configuration loss on restart. To recover: delete the IP Gateway Thing from the Inbox and restart. The Gateway will be rediscovered automatically. Note: Routers may appear as both tunneling and routing devices; choose the appropriate type from the Inbox. File-based configurations are not affected.

PythonScripting Automation

• Python "openhab.Timer" removed. Can be replaced with default Threading or Timer implementation.
• Changed parameter of "openhab.Registry.addItem"
• Replace "NotInitialisedException" with "NotFoundException" in "openhab.Registry.getItem, "openhab.Registry.removeItem", "openhab.Registry.getThing", "openhab.Registry.getChannel"
• "openhab.Registry.getItemMetadata", "openhab.Registry.setItemMetadata" and "openhab.Registry.removeItemMetadata" replaced by ".getMetadata().get", ".getMetadata().set" and ".getMetadata().remove"
• "openhab.Registry.safeItemName" move to "openhab.Item.buildSafeName"

Shelly Binding

• Thing type shellyplushtg3 was renamed to shellyplusht. Delete the existing things and re-discover the devices.

SMHI Binding

• Due to updates to SMHI's API, the channel ids have changed. Measures have been taken to ensure backwards compatibility, but to avoid future issues all items need to be relinked to the new channels.