openHAB 4.0.0 Milestone 3

This is a monthly milestone build for the upcoming openHAB 4.0 release, which brings many fixes and improvements.

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)

Introduction

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 follow these priniples:

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 did not set a state description (this is the part of the label enclosed in square brackets e.g. [%.2f °C]) you don't have to change anything.
• If you have set a state description and the unit is the same as the system default (https://next.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 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" }

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.
Have a close look at the output of the script during the upgrade process.

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.

New Add-ons

The following add-ons are newly introduced:

Add-on	Type	Issue
chatgpt	Binding	#14809
liquidcheck	Binding	#13287

The following improvements were made:

Runtime

Type	Issue	Change
Enhancements	2871	Allow managing persistence configurations and enable filters
	3268	Initial contribution of an CLI upgrade-tool
	3407	Add an AbstractStorageBasedTypeProvider
	3481	Add unit metadata for NumberItem
	3542	Improve precision of ColorUtil
	3548	Icon server: remove old style request with the state in the URL
	3550	Remove GenericScriptEngineFactory
	3559	List semantic tags
	3560	Remove redundant public and abstract modifiers from interfaces
	3568	Improve log message to identify profile's link
	3573	Add support for overriding holiday definitions
	3591	Make --dir param optional for upgradetool
	3593	Improve message when rule action fails
Bug Fixes	3572	Fix marketplace add-on services fail after upgrade
	3575	Consider auto-update policy from channel types
	3576	Improve thing updates
	3587	Change default imperial unit for length to inch
	3592	Fix non-unique module handler identifiers
	3598	Fix storing of StateDescriptionFragment in AbstractStorageBasedTypeProvider
	3608	Add dimension RadiationSpecificActivity

Add-ons

Add-on	Type	Issue	Change
AirQuality	Enhancements	14602	Enhance API error handling
airthings	Bug Fixes	15011	Adapt channels to new dimention for Radon measurements
anthem	Enhancements	14720	Add channel, refactor parser, add tests
avmfritz	Enhancements	14373	Add light blub color temperature support
boschindego	Enhancements	14829	Add device properties
danfossairunit	Enhancements	15002	Add UoM support for rotational speed channels
deconz	Bug Fixes	14827	Fix roller shutter status
easee	Bug Fixes	14903	Fix start/stop due to changed API
ecobee	Bug Fixes	14980	Delete OAuth access token when thing removed
evcc	Enhancements	14983	Adjust to API changes & add new channels for evcc 0.117.0
goecharger	Bug Fixes	14933	Avoid potential NullPointerException
harmonyhub	Enhancements	14507	Use AbstractStorageBasedTypeProvider
hdpowerview	Enhancements	13355	Add support for Generation 3
hue	Bug Fixes	14871	Fix NUPnP discovery
		14914	Restore UPnP discovery for old bridges
		14989	Fix NullPointerException in NUPnP discovery
iCloud	Bug Fixes	14661	Fix existing things stopped working and re-appeared as new in the inbox
imperihome	Enhancements	15014	Remove imperihome addon
influxdb	Enhancements	14806	Bump json from 20200518 to 20230227
		14959	Implement ModifiablePersistenceService
		15009	Support restoring unit for dimension items
	Bug Fixes	14888	Write asynchronously to database and improve performance
ipcamera	Enhancements	14728	Add Reolink API support
	Bug Fixes	14872	Fix servlet exceptions due to non unique names
		14909	Fix orphan ffmpeg process after stopping stream URL
jdbc	Enhancements	14874	Upgrade MySQL Connector/J to 8.0.33
	Bug Fixes	14987	Fix addon-info
jsscripting	Enhancements	14984	Add type translation for Instant and minor improvements
		14985	Allow configuring from add-on page
knx	Enhancements	14851	Add list of DPTs documenting implementation status
	Bug Fixes	14875	Fix decoding of DPT 242.600 and add tests
luftdateninfo	Enhancements	15012	[sensorcommunity] Rename binding to Sensor.Community
map	Bug Fixes	14825	[scale] Fix localization
mapdb	Bug Fixes	14900	Make serialization asynchronous
Meteoalerte	Enhancements	14811	Add an IconProvider
monopriceaudio	Enhancements	13936	Add support for additional amplifiers
mqtt.homeassistant	Bug Fixes	14858	Don't set range on current temp channel
netatmo	Enhancements	14780	Consolidate OAuth2 by using core implementation and storage
openwebnet	Enhancements	14357	Improve shutterRun calibration
		14819	Add a time stamp when an alarm zone event occurs
	Bug Fixes	14822	Fix for dimmer blocked after two OFF are received
remoteopenhab	Enhancements	14956	Use AbstractStorageBasedTypeProvider
renault	Enhancements	14846	Update default Kamereon API Key
robonect	Enhancements	14868	Improve job type configuration
rrd4j	Bug Fixes	14913	Write asynchronously to database
		14961	Do not create RRD file when querying data
senechome	Enhancements	14824	Add additional system states
sensebox	Bug Fixes	14879	Fix NPE after parsing invalid data
shelly	Enhancements	14532	Add support for Plus Smoke, Plus Plug-S/IT/UK/US, Plus Dimmer US, Pro 3EM; fix Gen1 sensor initialization
sonnen	Enhancements	14589	Update to API V2 of vendor and add PowerMeter
sonos	Enhancements	14920	Add support for Era 100 and Era 300
systeminfo	Enhancements	14501	Use AbstractStorageBasedTypeProvider
tapocontrol	Enhancements	14790	Move error messages to i18n
		14972	LightEffects for L530 can now be set
tesla	Bug Fixes	14922	Adapt binding to changed API from Tesla backend
velux	Enhancements	14817	Softer initialization after power failure
ventaair	Bug Fixes	14896	Fix typo Dimenionsless in channel definition
voicerss	Bug Fixes	14988	Fix service-id in addon.xml
Zigbee	Enhancements	804	Update ZSS library to 1.4.11
zoneminder	Enhancements	14906	Add support for setting the server run state

User Interfaces

UI	Type	Issue	Change
Basic UI	Bug Fixes	1897	Handle properly state updates to NULL or UNDEF
cometvisu	Bug Fixes	1826	Make sure that folder paths always end with a slash
Main UI	Enhancements	1818	Add a code tab to the Item editor
		1843	Sitemap and item config parsing adjustments
		1852	- Evaluate service as part of series's chart config
		1857	oh-sipclient: Various fixes & improvements
		1864	Improvements for UoM blocks & Extend getItemAttribute block
		1868	Toggle between item name or label
		1869	Add pattern to text of date block
		1870	Support storing timers in shared cache
		1871	Add new math_round block with round up, down and by decimals
		1875	oh-knob & oh-stepper: Add offset functionality
		1876	Developer sidebar: Support search in metadata value and config
		1877	Automatic shadow block conversion into real block
		1878	foreground-service: Listen to tab visibility change event
		1898	Add dictionary loop
		1899	Show toast instead of error when saving / running from code preview
		1901	Items: Add unit metadata for UoM (Number:) Items
	Bug Fixes	1849	Fix icons not displayed & not dynamic on all pages
		1865	Use right UID attribute in Thing picker
		1883	Transformation edit: Remove i18n string from Item state transform hint
		1884	Fix Things by binding & pages by type not in alphabetical order
		1887	Sitemap code generation: Quote colors
		1889	blockly] Fix picker update detection to allow shadow block conversion
		1894	oh-slider: Fix command sent on state update due to rounding
		1900	Item & Thing code tabs: Minor fixes
		1904	oh-repeater: Fix new data requested when css visibility changed