Thoughts on upgrading bindings to use new UoM features for Humidity

matt1 · February 2, 2024, 11:30pm

Been there myself plenty stick with it please as your contributions are valued greatly. Thanks.

This was raised in this github issue here as one of the dot points which I see @AndrewFG commented in there and hence is already aware. I have not read the history in the thread.

github.com/openhab/openhab-core

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

opened 09:42PM - 19 Oct 23 UTC

jlaur

enhancement

#3481 was quite a leap forward in terms of making UoM predictable and reliable. … Now that the smoke has cleared, I see a small opportunity to improve/fine-tune the user experience without changing anything in the UoM logic itself. A few examples where user experience could improve: - A binding integrating a washing machine or dishwasher provides water consumption for a `Number:Volume` channel. Default metric unit **m³** does not make much sense in this context. In most cases it should be either litres or gallons. - A binding integrating a car provides distances for a `Number:Length` channel. Default metric unit **m** is not ideal. In most cases **km** would be preferred (similar for imperial). - A binding provides relative humidity in percent for a `Number:Dimensionless` channel. Default unit **one** is not ideal, **%** would be expected. - A binding provides loudness in decibel for a `Number:Dimensionless` channel. Default unit **one** is not ideal, **dB** would be expected. Since the decision of which unit to use is (and should be) entirely up to the user, my only suggestion would be to add a possibility for bindings to give a **hint** about recommended units. The only usage of this hint would be for the UI to suggest reasonable default units when creating new items for channels. In other words, this will not control or override anything, or make the inner UoM logic more complicated in any way. It would exist in parallel as something exposed by the relevant REST methods to be consumed by the UI in order to better assist the user. Additionally, it should be easy/light-weight for bindings to provide such hints, and the bindings should not have to deal with `LocaleProvider` etc. or duplicate any logic that could be implemented in core and webui. The way I see this could be hinted by bindings would be to extend channel and channel-type definitions with an optional new tag. For example: ```xml <channel-type id="humidity"> <item-type>Number:Dimensionless</item-type> <label>Humidity</label> <description>Relative humidity</description> <category>Humidity</category> <state readOnly="true"/> <unit-hint>%</unit-hint> </channel-type> ``` Or perhaps: ```xml <channel-type id="humidity"> <item-type unitHint="%">Number:Dimensionless</item-type> <label>Humidity</label> <description>Relative humidity</description> <category>Humidity</category> <state readOnly="true"/> </channel-type> ``` And likewise for channel: ```xml <channel id="humidity" typeId="system.atmospheric-humidity"> <label>Humidity</label> <description>Relative humidity</description> <unit-hint>%</unit-hint> </channel> ```` I'm not sure if it makes sense for channels. Perhaps it would be better to require a custom channel type in order to provide such hints, as being able to override at channel level will increase the complexity. I can't think of any use cases since channel types needing specialized hints are probably too generic anyway. Now, a more complex example - the washing machine: ```xml <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 l"/> </channel-type> ``` In this case two units are provided. This is because the hints should be interpreted in the context of the regional settings. So for a US user, **gal** should be suggested, and for a European user, **l** should be suggested. I think this distinction is important if we want to get it right. The hint doesn't dictate anything, but in order to be truly helpful, we should still respect those settings, like we also do when item unit is completely missing and must be defaulted. Calling a method like this: `http://openhab:8080/rest/channel-types/miele%3AwaterConsumption` should then provide this hint (if this can be added while maintaining backwards compatibility): ```json { "parameters": [], "parameterGroups": [], "description": "Water consumption by the currently running program on the appliance", "label": "Water Consumption", "category": "Water", "itemType": "Number:Volume", "unitHint": "l,gal", "kind": "STATE", "stateDescription": { "pattern": "%.1f l", "readOnly": true, "options": [] }, "tags": [ "Measurement", "Water" ], "UID": "miele:waterConsumption", "advanced": false } ``` I'm not sure where the processing of this list of units should happen. Ultimately, for regional settings in Europe, the unit to default would be "l". I'm not into the architecture here, just outlining my proposal as detailed as possible. See also: - https://community.openhab.org/t/oh-4-units/148410/1

Many bindings in similar positions and not just humidity. This could also be a key reason why when v3 got introduced, we saw people going to another software package as easier then upgrading to v3 when rules needed editing due to datetime migration and channels to UOM. I escaped this because I was doing development and needed to delete and re-add things so often for testing, and getting new channels to show up, that I just adopted using defaults and making sure the bindings used nice names where possible instead of random UID values. I also do not care about historic values.

V4 did introduce Thing Upgrades, but many bindings devs don’t know it is there till they submit a PR, where does news of this get posted BTW? I myself have no idea of the scope of what it actually does until I just speed read the source code changes the PR made just now. Actually this feature has made me go Aargh and not want to implement changes, as now a 5 minute change turns into a 3 hour change as I need to look into how to do the update.xml only to find out what the reviewer of the PR is asking is not actually supported and possible.

When upgrading a channel from Number to Number:Dimensionless, that contains PercentType/DecimalType to now values of QuantityType<>

So there are 4 changes and please someone correct me if I am wrong but only the first 1 is actually automated and solved by the framework:

Thing need updating so the channel shows up correctly, this can be automated with above feature.
Items need to be changed to the new type.
Items linked to the new/changed channel in the case of where the name of channel has changed.
Historical data converted to work with the new item.

As for suggestions on ways forward:

You could leave the PercentType channel alone and add a new channel that has the newer support, now having to maintain two channels that do the same thing. I also believe its possible to hide a channel so new users do not see it and do not add it, but it keeps working as is. You could then add a WARN/INFO when the old channel is used to ask the user to migrate over to the new channel when they have time.

You/anyone/someone could extend the automation of the framework so that all the bindings do not get hit the same way, and its also temperature and many more. I am not capable of making such changes, still learning.

You could leave the channel alone if no one is asking for it to be upgraded, then the users must be happy. I doubt this is true as we have spent years telling users off for asking for new stuff in the forum.
We need to spend time where it is most valued or helps our own home. So if possible instead of changing 1 or x bindings, the time to even take the automation of thing changes up another level.

If the intention was to never add further automation to ease breaking changes, then we may as well have just automated a delete and re-add thing with same UID feature and gained an improvement without lumping extra coding onto all binding devs. It would also be nice if a channel keeps the same name and changes types that the binding dev does not need to add it to the XML and the core just handles it automatically especially for such common situations like temp and Humidity.

Of course this whole automating a breaking change is funny in a way to me because we should also consider what happens when a user wants to roll back, all of a sudden our upgrades and converting of historical data needs to be reversed or we now have what Home Assistant appears to have put the marketing spin of that they now have no “breaking changes” to now we only have “non backwards compatible changes”. This is less important here in openHAB as we can roll back just problematic bindings and addons keeping the upgraded core, in HA land you have to roll the entire lot back if any one of your 30 bindings have an issue and its pretty common that you do want to roll back compared to what happens here.

I got asked to add such a change in a PR to add it to the update.xml and as of last month it was not possible. If ~~you~~ anyone wants to know what is possible, this file outlines it…
https://www.openhab.org/schemas/update-description-1.0.0.xsd

Completely agree, so don’t misunderstand me when I say we need a better way to announce new dev features possibly in this forum like we have new openHAB releases annouced. Then we also need a FAQ done or a thread to discuss them, so we know the scope and some common use cases and how it effects people that contribute. So 1 person tests and then can post so we all do not need to re-do the tests. I do not believe this is in the dev documentation yet.