Unit hint in thing channels #4079

mherwege · 2024-02-04T21:47:41Z

Resolves #3854

To help the user in configuring the right unit when creating items from thing channels, one of the suggestions was to use a unitHint that could be provided by the binding developer. This PR implements the core part of this:

Add a unit-hint field to the channel type.
Expose this unit-hint field in the REST API.

The second part of this will have to be extending mainUI to use the unit-hint as proposed unit in configuration when available.

This can be especially useful for channels that provide % values, where QuantityType:Dimensionless has a default of Units.ONE. Note that an alternative solution with changing the default unit for QuantityType:Dimensionless has not gained support (#4077 and #4078).
This PR does help for users creating new items from channels in mainUI. It will not help for users using textual configuration.

For dimensions with different units in SI or US measurement systems, it is possible to provide 2 unit hints in one string separated by comma. The first one will be SI, the second US. The suggested one in the UI will depend on the measurement system setting.

This PR extends the thing-description-1.0.0.xsd and adds a new attribute to the input-type. Further investigation is required, as this may make it impossible to run bindings that have this field added on an older core (parsing the xml may fail). This is very similar to the situation described in #4062 for a change in addon.xml. To limit issues with newer bindings on older cores (going forward from 4.2), this may have to be solved in parallel.

Signed-off-by: Mark Herwege <[email protected]>

andrewfg · 2024-02-05T14:14:16Z

I was thinking if this is sufficient to cover the requirements. First I just want to make an observation that Number:Dimensionless is really a pretty vague class / concept which actually has several sub-classes in physical reality as follows.

Number:Dimensionless:Ratio for example mass ratio (e.g. g/kg), volume ratio (e.g. ppM)
Number:Dimensionless:ProportionOfMaximum for example heating power kW / max heating power kW, or litres in tank / tank size in litres, water content of air / maximum water carrying capacity or air [at that temperature], etc. (aka "percent")
Number:Dimensionless:RelativeToReference for example sound pressure level / reference sound pressure level (aka dB)
Possibly other cases? Please advise..

Anyway, to summarise, I think this would have the ability to cover all those needs.

When creating an item, the MainUI would have to offer a selection of a) all the most likely units suggested in the bullet points above, plus b) the unit hint proposed in this PR, plus c) a 'custom' option allowing the user to manually enter some other unit.

andrewfg · 2024-02-05T17:46:12Z

Apropos MainUI when creating a new item (see below) I have three suggestions..

When editing the 'Unit' field, the Dimension and State Description pattern should ideally synchronize with it.
Notwithstanding the objections of others elsewhere about 'one' not being the default in OH Core, I wonder if perhaps "%" could still be offered as the default in Main UI .. just a thought..
The 'Unit' field can be a drop down offering all the possible (currently defined) units supported by Number:Dimensionless

Signed-off-by: Mark Herwege <[email protected]>

mherwege · 2024-02-05T20:14:44Z

3. The 'Unit' field can be a drop down offering all the possible (currently defined) units supported by Number:Dimensionless

I don't think this can easily be generalized. Think about all the scale modifiers (micro, milli, centi, deca, hecto, kilo...). I know this is not relevant for Dimensionless, but I want to start with a general solution first, before trying to become specific.

jlaur · 2024-02-05T22:49:53Z

This PR extends the thing-description-1.0.0.xsd and adds a new field. Further investigation is required, as this may make it impossible to run bindings that have this field added on an older core (parsing the xml may fail).

Do you know if this would also be the case if added as an attribute to the item-type element?

<item-type unitHint="%">Number:Dimensionless</item-type>

I don't know if it makes any difference, but it seems somehow like a smaller change.

andrewfg · 2024-02-05T22:55:51Z

if this would also be the case if added as an attribute to the item-type element?

<item-type unitHint="%">Number:Dimensionless</item-type>

I agree. 'item-type" is the most obvious and logical holder for this attribute.

mherwege · 2024-02-05T22:59:56Z

I don't know if it makes any difference, but it seems somehow like a smaller change.

It doesn't make a difference (and is actually a bigger change, as item-type is now a String node and would have to be converted in an object).
The challenge with the xml files is that they are very unforgiving for extra data not in the code. The code goes through the elements and will fail on any field it does not recognize. And that's true for all xml processing. This is OK as long as it is stable, but it is hindering progress in many ways. I don't see a general solution for this.

mherwege · 2024-02-05T23:07:12Z

I agree. 'item-type" is the most obvious and logical holder for this attribute.

OK, will look into modifying it to be an attribute to item-type.

Signed-off-by: Mark Herwege <[email protected]>

andrewfg · 2024-02-06T13:00:57Z

@mherwege do you need to modify Rest API to include the new field JSON? But to answer my own question, I suppose GSON does that automatically..

mherwege · 2024-02-06T13:05:57Z

@mherwege do you need to modify Rest API to include the new field JSON? But to answer my own question, I suppose GSON does that automatically..

GSON does, but it needed to be added to the ChannelTypeResource in the Rest API package.

I tested with a modified UI from the linked PR (one example), and it was available in the UI and REST API.

mherwege · 2024-02-06T13:14:11Z

When editing the 'Unit' field, the Dimension and State Description pattern should ideally synchronize with it.

I replaced the default pattern with %.0f %unit% (in the UI PR). That should make sure it is always in sync with the item unit. Overriding it becomes an explicit choice. I don't see how to set Dimension form unit without having a full mapping (see next point).

The 'Unit' field can be a drop down offering all the possible (currently defined) units supported by Number:Dimensionless

There is no predefined list of allowed units (with their modifiers) I can query from the Rest API. So this is not easy to solve immediately and is subject for another potential enhancement.

Notwithstanding the objections of others elsewhere about 'one' not being the default in OH Core, I wonder if perhaps "%" could still be offered as the default in Main UI .. just a thought..

Could be done, however, without a list of potential units, nobody will know they have to set one if they want it. It is not a natural thing. % is more obvious to set explicitely.

jlaur · 2024-02-06T13:28:21Z

I tested with a modified UI from the linked PR (one example), and it was available in the UI and REST API.

Did you consider also this scenario:

<channel-type id="water-consumption">
	<item-type unitHint="l,gal">Number:Volume</item-type>
	<label>Water Consumption</label>
	<description>Water consumption by the currently running program on the appliance</description>
	<category>Water</category>
	<tags>
		<tag>Measurement</tag>
		<tag>Water</tag>
	</tags>
	<state readOnly="true" pattern="%.1f %unit%"/>
</channel-type>

where it should default either "l" or "gal" depending on configured measurement system?

mherwege · 2024-02-06T13:50:38Z

where it should default either "l" or "gal" depending on configured measurement system?

I considered it and created the code for it, but I must say I didn't explicitely test it.

andrewfg · 2024-02-06T15:20:06Z

without a list of potential units, nobody will know they have to set one if they want it.

That is why I was thinking of a drop down plus 'custom' input. Both one and % could be in the standard dropdown (with unit-hint preselected or % if unit-hint == null). The other standard options would be ppM, ppB, and dB. Any other unit, including those with milli, kilo, prefixes etc. could still be entered via the 'custom' input..

EDIT: the standard units being those here...

https://github.com/openhab/openhab-core/blob/c929e7dfe2b22298e3f99a3d95920dd08617befd/bundles/org.openhab.core/src/main/java/org/openhab/core/library/unit/Units.java#L105..L112

mherwege · 2024-02-06T16:32:42Z

That is why I was thinking of a drop down plus 'custom' input. Both one and % could be in the standard dropdown (with unit-hint preselected or % if unit-hint == null). The other standard options would be ppM, ppB, and dB. Any other unit, including those with milli, kilo, prefixes etc. could still be entered via the 'custom' input..

This makes sense for Dimensionless. But if you check the list of 'standard' units, you will notice it actually only lists exceptions not covered out of the box by the libraries. For instance, it creates mm/h, but km/h comes from the libraries. So the code you link is by no way exhaustive. Also, it would have to be created manually in the UI code.
I think what is need is a way to query a set of units for a given dimension through the REST API from core, and then show that list. That would make sure things are in sync with core and there are no two places to maintain it. Again, I think this goes beyond the scope of this (and the linked UI) PR. It is probably worth creating a specific enhancement request issue for it.

andrewfg

Assuming that openhab/openhab-webui#2312 can be approved without requiring further changes in this PR => LGTM

BUT -- just a reminder -- the following things will also need to be done..

Upload the revised XSD schema file to the OH main server. Otherwise the mvn build process for addons will fail due to a schema violation..
Update the respective addon developer readMe entry.

Closes openhab/openhab-core#4082. This PR adds: 1. A curated list of units to show as a drop-down list when creating a Number item with dimension. 2. The possibility to use a different default unit on item creation than the system default unit. 3. The ability to change unit and state description for items. 4. The ability to use the `unitHint` provided by channel types for "Link channel to Item" -> "Create a new Item". By default, the system default unit (for the configured measurement system) will be shown when editing or creating an item. `units.js` contains a number of frequently used units by dimension and measurement system. These will be available in a autosuggest dropdown list. It is still possible to not select from the list and use any other string as a unit. All units for the dimension in `units.js` will be in the dropdown list, but they will be sorted by measurement system. If the measurement system is set to US, imperial units will appear higher in the list. Units that have not explicitely been listed as SI or US will always appear higher. When typing a unit that is not in the curated list, a longer list will be used for autocompletion that considers allowed prefixes to base units and constructs all combinations. `units.js` also contains a field to set a different default unit on item creation than the system default unit. With openhab/openhab-core#4079, the REST API of channel types will provide a unit hint if defined in the binding channel types. If such information is available, this PR adds support for this to be the the suggested unit. If that information is unavailable, the UI will fall back to behavious described above. --------- Also-by: Florian Hotze <[email protected]> Signed-off-by: Mark Herwege <[email protected]>

andrewfg · 2024-03-07T04:02:02Z

@mherwege given that the UI change has now been merged, I think this one must be merged too. Or??

mherwege · 2024-03-07T07:40:28Z

@mherwege given that the UI change has now been merged, I think this one must be merged too. Or??

Would be nice, but the UI PR provides extra functionality without this already. Merging this PR will enable binding developers to include a unit hint in their channel definitions and the merged UI PR will consider it. There would be no change required to the UI PR.

openhab-bot · 2024-03-21T16:43:57Z

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/units-are-not-propagated-when-creating-items/154748/6

openhab-bot · 2024-04-03T14:19:29Z

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/inconsistent-percentage-behaviour/154595/40

jlaur · 2024-04-03T15:28:14Z

@mherwege - this PR fully resolves #3854, so if you change the first word in the PR description from "Solves" to "Resolves", the issue will be automatically closed when/if this PR is merged. 🙂

mherwege · 2024-04-03T16:04:20Z

@mherwege - this PR fully resolves #3854, so if you change the first word in the PR description from "Solves" to "Resolves", the issue will be automatically closed when/if this PR is merged. 🙂

Thanks and done.

J-N-K · 2024-04-04T14:19:58Z

bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/ChannelType.java

@@ -83,6 +86,7 @@ protected ChannelType(ChannelTypeUID uid, boolean advanced, @Nullable String ite
        }

        this.itemType = itemType;
+        this.unitHint = unitHint;


In general LGTM. Would it make sense to throw an IAE here when the item-type is not Number:* (similar to l. 85 above)?

Indeed, makes sense. Done.

Signed-off-by: Mark Herwege <[email protected]>

J-N-K

Thanks!

andrewfg · 2024-04-05T17:53:12Z

@mherwege / @J-N-K see this openhab/openhab-docs#2283

jlaur · 2024-04-06T12:25:28Z

@J-N-K - can you upload the new schema or is it only @kaikreuzer who can do that?

jlaur · 2024-04-06T14:15:16Z

This PR extends the thing-description-1.0.0.xsd and adds a new attribute to the input-type. Further investigation is required, as this may make it impossible to run bindings that have this field added on an older core (parsing the xml may fail). This is very similar to the situation described in #4062 for a change in addon.xml. To limit issues with newer bindings on older cores (going forward from 4.2), this may have to be solved in parallel.

I may have missed this, but did you analyze and find any impact on backwards/forwards compatibility?

Signed-off-by: Kai Kreuzer <[email protected]>

kaikreuzer · 2024-04-06T19:02:35Z

@jlaur It's very simple - you only need to create a PR against https://github.com/openhab/website/tree/main/.vuepress/public/schemas.
I just updated the schema with openhab/website#460.

jlaur · 2024-04-06T19:07:32Z

@jlaur It's very simple - you only need to create a PR against https://github.com/openhab/website/tree/main/.vuepress/public/schemas. I just updated the schema with openhab/website#460.

Thanks, and good to know! I assume some website build job is needed before the update is available here?
https://openhab.org/schemas/thing-description-1.0.0.xsd

jlaur · 2024-04-06T19:16:59Z

I assume some website build job is needed before the update is available here?
https://openhab.org/schemas/thing-description-1.0.0.xsd

I see it's already available now. 🙂

openhab-bot · 2024-06-05T06:21:30Z

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/unithint-error-in-xml-schema/156558/3

mherwege added 2 commits February 4, 2024 22:31

channelType add unitHint

1ff7cc0

Signed-off-by: Mark Herwege <[email protected]>

fix thing dto from xml generation

8ada35c

Signed-off-by: Mark Herwege <[email protected]>

mherwege requested a review from a team as a code owner February 4, 2024 21:47

mherwege marked this pull request as draft February 5, 2024 14:32

add xstream unit-hint alias

4e881ea

Signed-off-by: Mark Herwege <[email protected]>

mherwege marked this pull request as ready for review February 5, 2024 20:11

unitHint attribute of item-type

1649418

Signed-off-by: Mark Herwege <[email protected]>

mherwege mentioned this pull request Feb 6, 2024

Provide meaningful list of units in item form openhab/openhab-webui#2312

Merged

andrewfg mentioned this pull request Feb 6, 2024

Maintain curated list of units for a given dimension #4082

Closed

andrewfg approved these changes Feb 12, 2024

View reviewed changes

andrewfg mentioned this pull request Mar 30, 2024

[RfC] Make it possible for bindings to provide unit hints #3854

Closed

J-N-K reviewed Apr 4, 2024

View reviewed changes

Throw IAE on wrong use of unit hint

a16738c

Signed-off-by: Mark Herwege <[email protected]>

kaikreuzer requested a review from J-N-K April 5, 2024 08:21

J-N-K added this to the 4.2 milestone Apr 5, 2024

J-N-K approved these changes Apr 5, 2024

View reviewed changes

This was referenced Apr 5, 2024

Provide unit hint for system channel type atmospheric-humidity #4170

Merged

Provide unit hints for humidity/noise/volume channels openhab/openhab-addons#16614

Merged

andrewfg mentioned this pull request Apr 5, 2024

Add documentation for Unit Hint openhab/openhab-docs#2283

Merged

andrewfg mentioned this pull request Apr 5, 2024

[siemensrds] Remove r.H. from humidity state description pattern openhab/openhab-addons#16616

Merged

J-N-K merged commit c2cbefe into openhab:main Apr 6, 2024
3 checks passed

kaikreuzer added a commit to openhab/website that referenced this pull request Apr 6, 2024

Update thing-description schema for openhab/openhab-core#4079

5f7ce08

Signed-off-by: Kai Kreuzer <[email protected]>

kaikreuzer added a commit to openhab/website that referenced this pull request Apr 6, 2024

Update thing-description schema for openhab/openhab-core#4079 (#460)

4eb36cf

Signed-off-by: Kai Kreuzer <[email protected]>

mherwege deleted the unit-hint branch April 8, 2024 06:39

This was referenced Jul 14, 2024

AbstractStorageBasedTypeProvider doesn't store unitHint #4315

Closed

Add unitHint to AbstractStorageBasedTypeProvider.ChannelTypeEntity #4317

Merged

ccutrer mentioned this pull request Oct 28, 2024

Add min/max color temperature capabilities to channel state descriptions openhab/openhab-addons#17638

Closed

12 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Unit hint in thing channels #4079

Unit hint in thing channels #4079

mherwege commented Feb 4, 2024 •

edited

Loading

andrewfg commented Feb 5, 2024 •

edited

Loading

andrewfg commented Feb 5, 2024 •

edited

Loading

mherwege commented Feb 5, 2024

jlaur commented Feb 5, 2024

andrewfg commented Feb 5, 2024

mherwege commented Feb 5, 2024 •

edited

Loading

mherwege commented Feb 5, 2024

andrewfg commented Feb 6, 2024

mherwege commented Feb 6, 2024 •

edited

Loading

mherwege commented Feb 6, 2024 •

edited

Loading

jlaur commented Feb 6, 2024

mherwege commented Feb 6, 2024

andrewfg commented Feb 6, 2024 •

edited

Loading

mherwege commented Feb 6, 2024

andrewfg left a comment •

edited

Loading

andrewfg commented Mar 7, 2024

mherwege commented Mar 7, 2024

openhab-bot commented Mar 21, 2024

openhab-bot commented Apr 3, 2024

jlaur commented Apr 3, 2024

mherwege commented Apr 3, 2024

J-N-K Apr 4, 2024

mherwege Apr 4, 2024

J-N-K left a comment

andrewfg commented Apr 5, 2024

jlaur commented Apr 6, 2024

jlaur commented Apr 6, 2024

kaikreuzer commented Apr 6, 2024

jlaur commented Apr 6, 2024

jlaur commented Apr 6, 2024

openhab-bot commented Jun 5, 2024

Unit hint in thing channels #4079

Unit hint in thing channels #4079

Conversation

mherwege commented Feb 4, 2024 • edited Loading

andrewfg commented Feb 5, 2024 • edited Loading

andrewfg commented Feb 5, 2024 • edited Loading

mherwege commented Feb 5, 2024

jlaur commented Feb 5, 2024

andrewfg commented Feb 5, 2024

mherwege commented Feb 5, 2024 • edited Loading

mherwege commented Feb 5, 2024

andrewfg commented Feb 6, 2024

mherwege commented Feb 6, 2024 • edited Loading

mherwege commented Feb 6, 2024 • edited Loading

jlaur commented Feb 6, 2024

mherwege commented Feb 6, 2024

andrewfg commented Feb 6, 2024 • edited Loading

mherwege commented Feb 6, 2024

andrewfg left a comment • edited Loading

Choose a reason for hiding this comment

andrewfg commented Mar 7, 2024

mherwege commented Mar 7, 2024

openhab-bot commented Mar 21, 2024

openhab-bot commented Apr 3, 2024

jlaur commented Apr 3, 2024

mherwege commented Apr 3, 2024

J-N-K Apr 4, 2024

Choose a reason for hiding this comment

mherwege Apr 4, 2024

Choose a reason for hiding this comment

J-N-K left a comment

Choose a reason for hiding this comment

andrewfg commented Apr 5, 2024

jlaur commented Apr 6, 2024

jlaur commented Apr 6, 2024

kaikreuzer commented Apr 6, 2024

jlaur commented Apr 6, 2024

jlaur commented Apr 6, 2024

openhab-bot commented Jun 5, 2024

mherwege commented Feb 4, 2024 •

edited

Loading

andrewfg commented Feb 5, 2024 •

edited

Loading

andrewfg commented Feb 5, 2024 •

edited

Loading

mherwege commented Feb 5, 2024 •

edited

Loading

mherwege commented Feb 6, 2024 •

edited

Loading

mherwege commented Feb 6, 2024 •

edited

Loading

andrewfg commented Feb 6, 2024 •

edited

Loading

andrewfg left a comment •

edited

Loading