RFC: Change Number item type for improved UoM handling #3282
Description
There have been various discussions (#3167, #3247, #3248, #3258, forum about the handling of UoM in Number items. Let me first summarize the current state, then the proposed state and finally the migration path for existing installations:
The 3.x situation
There are two "types" of Number items: plain Number and Number:dimension (like Number:Temperature). In contrast to the documentation they both accept DecimalType and QuantityType state updates and commands. The user needs to know the correct dimension, which is very likely the case if we talk about length or temperature but maybe not so obvious for other cases (take a second and ask yourself if you know the correct dimension for lx, in German it's "Helligkeit" which has more than ten different translations according to dict.leo.org and Google translator returns a wrong translation for our use-case).
State updates
| State | Number |
Number:Temperature |
|---|---|---|
DecimalType |
as-is | add default unit (see below) |
QuantityType |
strip-unit | as-is (if unit compatible and same measurement system) |
| convert (if unit compatible and other measurement system | ||
| reject (if unit incompatible |
Command handling
| Command | Number |
Number:Temperature |
|---|---|---|
DecimalType |
as-is | as-is (if linked to a channel with accepted item-type Number) |
add default unit (if linked to a channel with accepted item-type Number:dimension) |
||
QuantityType |
as -is | as-is |
Persistence
Persistence only stores plain numbers
| State | stored | restored |
|---|---|---|
DecimalType |
as-is | as-is |
QuantityType |
convert to default unit and strip unit | add default unit |
The default unit is determined (in that order)
- from the state description
- from the list of system default units
If the state description contains %unit% the unit is used as provided by the binding.
The 4.x proposal
The Number:dimension item type is removed. Instead a new metadata unit is introduced. Setting unit enables the item to handle UoM. The user does not need to care about the dimension, he just configures a unit he expects for this item which is much more convenient for those of us that are non-native speakers and don't deal with units in foreign languages in professional work.
State update
| State | Number without unit |
Number with unit |
|---|---|---|
DecimalType |
as-is | add configured unit |
QuantityType |
strip-unit | convert to configured unit (if unit compatible) |
| reject (if unit incompatible |
Command handling
| Command | Number without unit |
Number with unit |
|---|---|---|
DecimalType |
as-is | add configured unit |
QuantityType |
strip unit | as-is (if unit compatible) |
Persistence
| State | stored | restored |
|---|---|---|
DecimalType |
as-is | as-is |
QuantityType |
convert to configured unit and strip unit | add configured unit |
Examples
ItemStateEvent |
unit= metadata |
stateDescription |
internal value | persisted value | restored value | displayed value |
|---|---|---|---|---|---|---|
| 5.0 | none | none | 5.0 | 5.0 | 5.0 | 5.0 |
| 5.0 | none | %.0f | 5.0 | 5.0 | 5.0 | 5 |
| 5.0 | none | %.0f °C | 5.0 | 5.0 | 5.0 | 5 °C |
| 5.0 | °C | none | 5.0 °C | 5.0 | 5.0 °C | 5.0 °C |
| 5.0 | °C | %.0f K | 5.0 °C | 5.0 | 5.0 °C | 278 K |
| 5.0 | °C | %.0f %unit% | 5.0 °C | 5.0 | 5.0 °C | 5 °C |
| 5.0 °C | none | none | 5.0 | 5.0 | 5.0 | 5.0 |
| 5.0 °C | none | %.0f | 5.0 | 5.0 | 5.0 | 5 |
| 5.0 °C | none | %.0f °C | 5.0 | 5.0 | 5.0 | 5 °C |
| 5.0 °C | °C | none | 5.0 °C | 5.0 | 5.0 °C | 5.0 °C |
| 5.0 °C | °C | %.0f K | 5.0 °C | 5.0 | 5.0 °C | 278 K |
| 5.0 °C | °C | %.0f %unit% | 5.0 °C | 5.0 | 5.0 °C | 5 °C |
| 5.0 K | °C | none | -268.15 °C | -268.15 | -268.15 °C | -268.15 °C |
| 5.0 K | °C | %.0f K | -268.15 °C | -268.15 | -268.15 °C | 5 K |
| 5.0 K | °C | %.0f °C | -268.15 °C | -268.15 | -268.15 °C | -268.15 °C |
| 5.0 K | °C | %.0f %unit% | -268.15 °C | -268.15 | -268.15 °C | -268.15 °C |
The "internal value" is used in ItemStateChangedEvent and (if accepted ItemStateUpdatedEvent).
The migration
Plain Number items
There is nothing to to for plain Number items. They work like they did before.
Managed Number:dimension items
With #3268 (which could also be run automatically on upgrade, in contrast to what is written in the PR) the dimension could be removed from the item-type. If a dimension is found, the unit metadata is added. In case a state description is present that contains a unit, that unit is used, if not, the system default unit is used. IMO an automatic conversion is desired here, because the user expects plug-and-play for managed entities.
Unmanaged (textual) Number:dimension items
This needs to be discussed. @spacemanspiff2007 offered to provide a script that can be run during update to offer a similar functionality. The question is whether this should be run automatically or on demand, because usually users of textual configuration do not expect any changes to their configuration during upgrade.
UI
UI needs to be adapted to only present Number instead of a list of many items. It should show an additional field unit on creation only, later the unit should be editable like other metadata.
The decision
@openhab/maintainers and @openhab/architecture-council:
Since this requires quite some refactoring, I would like to hear your opinions on that before I start the implementation. IMO the new proposal is easier to understand and much more consistent than the current situation. It allows decoupling of internal state and presentation (because state description is no longer taken into account for determining the unit). To allow extensive testing we should reach a decision here within the next three weeks (i.e. until 2023-01-15) and have the PR merged latest 2023-03-31.
Metadata
Metadata
Assignees
Type
Projects
Status