openHAB 2.2 Release Notes

New and Noteworthy

The openHAB 2.2 release 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. Besides many interesting new bindings (e.g. integration to Loxone, LG TVs and iCloud), there are many exciting tools around setup and administration: The new Home Builder interface enables newbies to easily generate initial item and sitemap files to start from. All textual configuration is as comfortable as never before through the VS Code Extension, which now supports syntax checking, content assist and a lot more and which is now the official replacement of the previous "Designer". Last but not least, there are now backup, restore and update scripts available for Linux, MacOS and Windows likewise.

Quick links:

Notes about the Core runtime
Notes about the Add-ons
Upgrade Process for openHABian, APT, RPM, Manual Installations
Breaking Changes that require manual interaction after the upgrade.

Relevant Changes

Core Runtime

Enhancements

#220 - Updated to new openHAB logo
#609 - Added home builder to standard package
#507 - Backup and restore scripts for Linux/MacOS
#512 - Backup script for Windows
#593 - Formatted the demo / example files
#594 - Increased thread pool sizes
#608 - Reduced scan frequency of FileInstall and increased its start level
#473 - Upgrade script for Windows
#570 - Upgrade to Karaf 4.1.3 and Jetty 9.3.22
#185 - Added support for dashboard links to external services.
#217 - Dashboard internationalization
#256 - Improved the feature installation logic
#4291 - Charts Enhancements: Themes, DPI, legend hiding
#1854 - Added sumSince method in scripts/rules
#4462 - Enhanced rule interpretation error messages
#4148 - Exposed a Language Server
#3930 - Implemented option to choose default network interface
#4439 - Improved scale transformation service
#4379 - JsonPath transformation service now complies with the contract
#3001 - Provided a trigger for thing Online/Offline status in rules.
#4414 - Redesigned volume icon
#4197 - TTS voice selection now done using locale matching based on RFC 4647

Bug Fixes

#4380 - Charts: Explicitly close the image output-stream to avoid resource leaks
#3752 - Added Composite Jobs for range events if scheduled at same instant
#4051 - Added support for URIs with user info but no password for the ProxyServlet
#3855 - Allow JSR223 scripts with same name in different directories
#2080 - avoid NPE if default TTS cannot be found
#3795 - Break circle dependencies in GroupItem members
#4524 - Improved error handling in ChartServlet
#3832 - Script/rules now gracefully handle null return values
#1846 - Set correct percent value for Rollershutter item

Add-ons

The following add-ons are newly introduced with the 2.2 release:

The following changes were done on existing 2.x add-ons:

Paper UI

Enhancements

#3782 - Reworked bindings list view & binding detail view
#3755 - Added options for language & regional settings
#4256 - Added time zone configuration option
#4568 - Introduced config option provider for serial ports

Bug Fixes

#3731 - Performance improvements on control page
#4340 - Added rollershutter group type
#4120 - Allow negative integer input for parameters with default pattern
#3968 - Prevent duplicate things during digest cycle

Basic UI

Enhancements

#4336 - Use chart themes in UI themes
#4338 - Internationalization support
#4386 - Support for HTTP live streams

Bug Fixes

#3749 - Escape HTML characters
#4534 - Fixed refresh of hidden/visible image/chart
#3958 - Set widget value regardless of whether or not visibility has changed
#3846 - Reload page if sitemap has been changed

HABPanel

Enhancements

#225 - Community widget gallery
#210 - New Selection widget
#202 - Import widgets from a GitHub repository
#233 - New openHAB logo and meta tags for iOS Safari
#215 - Add header & drawer display options
#251 - Include all data in raw local panel configuration editor
#207 - Item picker: icons for item types
#197 - Icon picker: allow custom icons or custom URLs
#204 - Experimental: custom widgets for main menu tile
#216 - Experimental: custom widgets for drawer and headers
#250 - Experimental: option to hide dashboard from side drawer menu
#199 - Experimental: new dashboard options - mobile mode, row height
#226 - Chart widget: send "Theme" parameter for "default" charts
#229 - Chart widget: add "Show legend" option for "default" charts
#205 - Frame widget: refresh option
#208 - Image widget: accept Image items
#228 - Image widget: make the background color configurable
#206 - Timeline widget: refresh automatically

Bug Fixes

#214 - Improve the initial rendering of several widgets
#250 - Improve the dashboard settings saving mechanism
#217 - Don't wrap long dates in drawer
#195 - Dummy widget: use raw state for icon
#227 - Frame widget: fix for query strings
#239 - Image/frame widgets: autorefresh fixes, optional cache busting
#213 - Knob widget: fix options initialization and improve labels
#249 - Knob widget: fix range settings and default text color
#220 - Selection widget: display label of selected choice if provided
#218 - Slider widget: display slider even if it has an invalid value
#248 - Template widget: refresh upon modal rendered
#203 - Timeline widget: fill last partition & better tick format for 2M/4M periods
#194 - Timeline widget: auto scale tick format

2.x Addons

AllPlay Binding

Enhancements

#2688 - Added support for zone (multiroom) creation and deletion

Astro Binding

Enhancements

#3725 - Background discovery for location changes

Bug Fixes

#3807 - Fixed invalid event creation
#3811 - Tidied up set of scheduled futures
#4061 - Fixed applying earliest and latest config on channel
#4131 - Schedule Jobs 30sec after midnight to ensure to be on the next…
#4158 - Fixed sun phase calculation
#4437 - Use float formatting instead of int for distances on channels
#3746 - Synchronous execution of Astro Startup Jobs

AVM FRITZ! Binding

Enhancements

#2774 - Added support for new FRITZ!DECT 301 device

Chromecast Binding

Enhancements

#2097 - Expose metadata from media status

CometVisu UI

Enhancements

#2536 - Added feature to Auto-install CometVisu-Client

CoolMasterNet Binding

Bug Fixes

#2790 - fixed binding startup error

Gardena Binding

Enhancements

#2494 - Added support for Smart Pressure Pump

Harmony Hub Binding

Enhancements

#2678 - Added trigger channels for activity starting and activity started events from the hub

HD PowerView Binding

Bug Fixes

#2521 - Fix configuration to use String for id

Homematic Binding

Enhancements

#2554 - Added support for Homematic IP blind actuator

Bug Fixes

#2932 - Don't cache data points of reconfigurable channels
#2785 - Fixed connection tracker timeout for CCU1

Hue-emulation

Enhancements

#2145 - Added support for Google Home

Keba Binding

As of 2.2 the Keba binding supports all P20 and P30 variations of the Keba EV Charging stations. In doing so the supported Thing type changed from "kecontactp20" to "kecontact", and users should therefore alter their .things definition files.

Kodi Binding

Enhancements

#2304 - Add channels for fan art and thumbnail

LIFX Binding

Enhancements

#4231 - Added optional host configuration parameter
#4448 - Updated supported products
#3816 - Update ThingStatus at most once a second
#3324 - Added further LIFX properties

Bug Fixes

#3772 - Fixed powerOnBrightness is ignored when empty in the things file

Lutron Binding

Enhancements

#2846 - Adding RadioRA Classic support

MiHome Binding

Enhancements

#2704 - add new channel for smoke sensor
#2487 - Added support for Aqara Door/Window & Aqara Temperature, Humidity and Pressure sensors
#2528 - Added support for Aqara Switch
#2657 - Xiaomi Water Leak sensor and Aqara motion sensor support.

Netatmo Binding

Enhancements

#2561 - Added new channels for NAModule4

The binding has been largely updated and enhanced with the support of new devices like the Welcome camera. You will have to update your thing definition (or re-create them if you are using Paper UI) because few parameters have been renamed like for example "equipmentId" renamed into "id".

Bug Fixes

#2682 - Global review of Binding to integrate Welcome Camera

Network Binding

The binding has been enhanced with many new features like ARP ping, an iOS specific presence detection and correct access rights for DHCP. The former "device" Thing has been split into "pingdevice" and "servicedevice". The following configuration is now a binding configuration:

use_system_ping: It is not recommended to change this configuration, but rather rely on the auto-detection.

Onkyo Binding

Enhancements

#2762 - Added support for TX-NR737

PioneerAvr Binding

Enhancements

#2540 - Zone2 / Zone3 / HDZone Volume Control

RFXCOM Binding

Enhancements

#2511 - Added support for BBQ temperature sensors
#2689 - Allow Rfy things to send on venetian blind channels.

Bug Fixes

#2433 - Corrected timeout bug for TCP connected bridges
#2507 - Added missing temperature and chill temperature for Wind devices

SamsungTV Binding

Enhancements

#2357 - Added support for manual configured tv

Silvercrest Binding

Enhancements

#1954 - Added support for Easy Home

Sonos Binding

Enhancements

#4429 - Added support for Sonos One player
#3740 - Added new channel clearqueue
#3800 - Added state description on few channels
#3940 - Handle Google Play Music radio
#4229 - Play TuneIn by a station id
#3964 - Added further properties

Bug Fixes

#3883 - Fixed bug with notification timeout handling
#4415 - Fixed discovery for old Sonos ZP80 and ZP100
#4500 - Optimized cover art download
#3808 - Improved notification timeout handling

Squeezebox Binding

Enhancements

#2479 - Add support for LMS authentication

TRADFRI Binding

Enhancements

#4271 - Added support for RGB bulbs
#4366 - Added FLOALT panels
#4373 - Added support for remote controller and motion sensor devices

Bug Fixes

#3895 - Avoid NPE while handling INCREASE/DECREASE commands
#4351 - Fixed bug in color space conversion
#4344 - Fixed color light bug when brightness is less than 2%
#4530 - various lifecycle improvements and fixes

WiFiLED Binding

Bug Fixes

#2493 - Fix HIGH CPU during fading during transitions

Zigbee Binding

Enhancements

#35 - Add Ember dongle firmware update support
#56 - Add IAS Sensors and Occupancy Sensor
#21 - Add option to configure Ember baud rate
#40 - Add OTA Firmware update to ZigBee thing
#28 - Add Telegesis dongle and Telegesis firmware update
#52 - Add Telegesis support for IAS cluster and update temperature converter
#51 - Adds refactoring to avoid duplicate nodes when the network address changes

ZWave Binding

Enhancements

#738 - Add ThermostatMode BOOST
#747 - Added serial-port context to config parameter

Bug Fixes

#758 - Avoid NPE during Thing update

The following changes were done on existing openHAB 1.x add-ons:

Anel Binding

Enhancements

#5264 - Compatibility with Anel Firmware 6.1.

Bticino Binding

Enhancements

#5352 - Added support to OpenWebNet password to bticino binding.

CalDav Binding

Bug Fixes

#5274 - Fix problem with resource paths containing curly braces.

Cardio 2é Binding

Enhancements

#5151 - Added config file and registered in POM.xml

Denon Binding

Enhancements

#5342 - Send commands over telnet connection + several other improvements

Bug Fixes

#5258 - Protect against null values in secondary zone information.

DynamoDB Persistance

Enhancements

#5333 - DynamoDB SDK update 1.11.213

eBUS Binding

Bug Fixes

#5271 - Fix escaping issue if slave CRC is 0xAA

Epson Projector Binding

Enhancements

#5307 - Add additional ColorMode and AspectRatio values (from 5030UB projector)
#5339 - Fixed logging

Fritzbox TR064 Binding

Enhancements

#5295 - add items for dsl/wan statistics (#5221)
#5296 - get wan ip from external router (#5283)
#5385 - reduced logging level as we already log success/failure anyhow

HTTP Binding

Enhancements

#5270 - Don't log an error when the "format" configuration setting is found

Bug Fixes

#5297 - Add transformation support for POST

InfluxDB Persistance

Bug Fixes

#5239 - fix state type calculation of group items

JDBC Persistence

Enhancements

#5301 - Decreased logging level

KNX Binding

Bug Fixes

#5384 - avoid NPE and applied code formatter

LightwaveRF Binding

Bug Fixes

#5232 - Don't let the energy monitor crash OH

mapDB Persistance

Bug Fixes

#5315 - Avoid NPE if null is passed to writeUTF() method

Novelan Heatpump Binding

Bug Fixes

#5383 - Prevent null pointer exceptions during disconnect.

OneWire Binding

Enhancements

#5321 - Fix typo in onewire configuration

Satel Binding

Bug Fixes

#5207 - Binding deactivation fix

Swegon Binding

Enhancements

#5299 - Support for RAW PDUs

TCP Binding

Enhancements

#5367 - Prevent null pointer exceptions during shutdown

Telegram Action

Enhancements

#5265 - Distinguish between "no image retrieved" and "unrecognized image" errors
#5337 - sendTelegramPhoto has now configurable timeout and retry

Weather Binding

Enhancements

#5280 - Added mapping for OpenWeatherMap for channel 'gust'
#5349 - Fixed parsing of rain value in forecast data
#5294 - Replaced org.apache.commons.httpclient dependency with ESH HttpUtil

Bug Fixes

#5348 - Added NPE safe-guard if HTTP request fails

Upgrade Process

openHABian

If you are working with an openHABian setup, the upgrade is quite easy. Regardless of if you are currently using the openHAB 2.1 stable release or one of the latest 2.2 SNAPSHOT builds, switching to openHAB 2.2.0 stable is done in just a few steps:

Connect to the SSH command line and execute: sudo openhabian-config
Select the "Update" option
Wait for the openHABian update to finish, reenter the openHABian configuration tool
Select the "openHAB 2.2.0 stable" option

Package-based Installations

For package based installations, you may be asked to replace some configuration files in /var/lib/openhab2. For best results select yes at each of these prompts. Old configurations can be found in the same place, but with dpkg-old appended to it.

APT

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 2.2.0 and it's optional addons with:

sudo apt-get install openhab2=2.2.0-1

## optional addons for offline installation ##
sudo apt-get install openhab2-addons=2.2.0-1
sudo apt-get install openhab2-addons-legacy=2.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 2.2.0 and its optional addons with:

sudo yum install openhab2-2.2.0

## optional addons for offline installation ##
sudo yum install openhab2-addons-2.2.0
sudo yum install openhab2-addons-legacy-2.2.0

Manual Installations

Offical update scripts are available that let you update your 2.1 installation to version 2.2:

Linux/MacOS

Change to your openHAB root directory (e.g. cd /opt/openhab2)
If you are upgrading from a version after and including 2.1.0, then simply run the command:

sudo ./runtime/bin/update 2.2.0

If you are upgrading from a version before 2.1.0, you can download and run the update script in one command using:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distro/2.2.0/distributions/openhab/src/main/resources/bin/update)" -- 2.2.0

Windows

This is the first stable version with a Windows update script, therefore you will need to download the one packaged with 2.2.0 to upgrade. To do this, make sure to download update.ps1 and backup.ps1 from the github repository (right-click the page then "Save-As") then save it to the runtime/bin folder of openHAB. To start the update process, run PowerShell as an administrator and use the following commands. Assuming you have openHAB saved in C:\openHAB:

cd C:\openHAB
. .\runtime\bin\update.ps1
Update-openHAB -OHVersion 2.2.0

Now that openHAB has updated, you only need to run the above commands again for future versions.

Breaking Changes that Require Manual Interaction after the Upgrade

General Changes

The logging framework has been upgraded to log4j2, which results in a different format of the logger configuration. So in case you have done changes to the org.ops4j.pax.logging.cfg file, please re-apply those to the new version in the log4j2 format. For an example configuration, see this community post.
The configuration for the Inbox auto-approval (within services/runtime.cfg) has changed from autoapprove:enabled to org.eclipse.smarthome.inbox:autoApprove.

Rules

*.rules file are now validated upon startup. Warnings are logged, but won't have any other impact, while files with errors will from now on be ignored by the runtime.
DateTimeType.getCalender() has been deprecated. The new DataTimeType.getZonedDateTime() should be used instead. In rules, (riseStart.state as DateTimeType).calendar.timeInMillis can be replaced with (riseStart.state as DateTimeType).zonedDateTime.toInstant.toEpochMilli to avoid the validation warning.

Running openhab using docker

There are small changes for running openHAB using docker. For both docker and docker-compose you have to pass a parameter to inform docker that it should 'allocate a pseudo-TTY'. The examples have been updated but the short explanation is that docker run needs either the -t or --tty parameter and docker-compose needs configuration format 2.1 and tty: true.