openhab/openhab-distro 4.0.0.M3

openHAB 4.0.0 Milestone 3

on GitHub

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:

The following improvements were made:

Runtime

Add-ons

User Interfaces