I have a couple of existing bindings since OH v2.x with Relative Humidity channels that return PercentType state values. I have not been 100% following the recent improvements in UoM but I got the feeling that there is now a specific QuantityType for Relative Humidity? Or a QuantityType for Dimensionless? So I am looking for advice if I should update those bindings from returning PercentType to QuantityType (with respective changes to the state definition in the channel xml file, and readme files). I guess this is probably more future proof, but risks to upset existing users with a breaking change. => WDYT?
I think QuantityType is indeed the more appropriate type for this. I see PercentType as mostly relevant for dimmers and rollershutters.
At the same type, the conversion will be a hassle, especially because for humidity, you would use QuantityType:Dimensionless, and that has a default unit of ONE, not %. Unless you change the unit on the item, it will get stored as fractions, instead of percent, while it was stored as 1 to 100 decimals before.
I think you could provide update instructions in the change to the binding channels, but I am not sure it can be fully automated as the unit needs to be set on the item.
Which (therefore) means that all existing users will lose their persisted history of that channel…
Unless they manually set the unit on the item to be %. So you need manual update instructions, beyond the automated ones.
Aargh. I am rapidly losing the will to do this…
PS it seems to me that (at least for future developers) we should think about creating a QuantityType Humidity in core based on a respective Unit.RELATIVE_HUMIDITY that has a minimum value of 0 and a maximum value of 100 and a unit “% R.H.” … and yes I am fully aware that this comment will provoke a furious over- reaction from UoM purists… 
See this discussion: [RfC] Make it possible for bindings to provide unit hints · Issue #3854 · openhab/openhab-core · GitHub
I think most would be solved if the default unit for Dimensionless would be %, instead of ONE. I see no cases where ONE would be useful. And dB is the less likely unit and more logical to set when creating an item.
1 Like
QuantityType Dimensionless is the unit category for all ratios, including percentages.
I would recommend that. Since a relative humidity can be a fraction of a percent, PercentType isn’t that good of a fit for the data.
I’m not entirely positive that it would be a breaking change. I know if you have a plain Number without units and you pass it an update with units, the units are simply thrown away. I would hope the same is true for PercentType. In that case, so long as you only pass whole numbers to the PercentType it should throw away the unit part and it shouldn’t break your existing users.
All of that needs to be tested and verified though.
I’m slowly advocating for a change to that. % is the most common use case for Number:Dimensionless, it should be the default.
If the State Description for the Items currently have a format like %d % or the like and they are managed Items, the upgradeTool should work to identify those Items lacking unit metadata and create it based on the unit in the state description.
Not lose but without adding the unit metadata the new data will not patch the old data and the carts will be wrong. But as soon as the unit=% metadata is added the values will match the old data.
Going forward, everywhere in MainUI that a Number:X Item can be created (except add items from text definition) the default unit that will be used is shown to the user and they have the opportunity to change the unit before the Item is created. So this is mostly a problem for existing users.
1 Like
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.
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.
There is this issue mentioning that problem:
During an upgrade, the upgradeTool could theoretically handle 2 and 3 for managed Items (with changes to the tool of course). 4 may or may not be required at all if the actual number values stored by the new item doesn’t change. For example, if the previous Item was a Dimmer and the new one is a Number:Dimensionless with unit of %, the value stored will still be between 0 and 100 so the historic data is still good.
The unit doesn’t get saved to persistence, just the date time and the value gets saved. The unit gets inferred based on the unit metadata.
I think marking it as advanced would be sufficient.
I believe the intention was to make it so that old Things could still continue to work in new OH instances without needing to be recreated to pick up changes in the first place.
My understanding is this is already built into the upgradeTool. Binding authors need do nothing to get this behavior. The tool iterates through the Items and adds unit metadata based on the following priority:
- state description pattern
- unit the Channel reports (somehow?) it publishes
- system default (in this case the metadata is not added)
I don’t know the specifics but none of these require any special action on the binding authors part.
The upgradeTool ribs as part of the upgrade process or can be run manually.
I think it’s worth noting that all of these changes are included in the release announcements too. It’s not just user facing charges listed. All the PRs are listed there.
I’m not saying we don’t need a better way, but they are announced.
Agree, however unlike other changes I feel this one is very different:
- Reviewers need to know to get PR to implement this stuff
- Addon devs need to know to put it in and know some basic background and a basic how and why otherwise we will get annoyed at the change if we do not know the why and how.
- Appears after 6 months it is still not documented and we have to dig through PR, forum posts and other ways to try and piece together the puzzle.
@laursen Thank you for the link, after doing hours of reading I finally now understand the choice much better. To sum it up, it is because we have bindings like MQTT where a user can add their own channels and create their own labels for these user created channels. So we can not do an auto delete and recreate thing. This is an example of a basic WHY that needs to be communicated so devs understand.
@AndrewFG
To get back on topic/question.
This link should show examples of upgrade instructions
https://github.com/search?q=repo%3Aopenhab%2Fopenhab-addons+instructions.xml&type=code&p=1
If you use on your channel and if any of the parameters/metadata/xml data is not supported, they still get pulled in because the upgrade code uses the thingBuilder to just delete and re-add the channel, so any new stuff in your thing-types.xml file should get pulled in.
I can confirm that I have already tested this recently and <state xxxxx pattern= changes will get updated just fine. @rlkoshak has confirmed it should not be an issue for history so it appears to be easy to solve in your case.
How users rules will handle the change, I have not looked at. The update/instructions.xml has made it better and helped to reduce breaking changes going forwards. What will break still I am interested to hear if you test it and what breaks.
I’ve already suggested here to have a new forum subcategory to request and discuss new features ahead of implementation time.
ping @Kai
My experience with discussion of new features is: no one participates before there is code.
I believe in parts the reason for that is that for a user it’s unclear where and how to address this.
Which is what I want to improve.
But there’s a user-dev knowledge gap, too. Users know nothing about code and implementation restrictions, what can be done and what cannot so often have unrealistic expectations.
Asking and discussing upfront can help narrowing that gap.
^
It probably needs a forum chapter “New & Upcoming” with two sub- chapters “Developer” and “User”. Plus perhaps an editorial process to tag posts by degree of newness and archive when no longer so new…
At least core development issue should be discussed on GitHub.
2 Likes