OH4 how to define UoM in binding configuration - units can't be set manually


I’m totally confused, maybe I’m doing something wrong. Since the update to OH4 my binding only shows distances in m instead of km and pressures in hPa instead of bar. The values are technically correct (I set 1km and get 1000m), but this is according to the documentation not how it should be.

So I tried to set the right unit in the channel-config, but still the unit is wrong.

This is an example channel config:

	<channel-type id="range-fuel-channel">
		<label>Fuel Range</label>
		<state pattern="%d km" readOnly="true"/>

and in the code I set the value like this:

Unit<Length> lengthUnit = MetricPrefix.KILO(SIUnits.METRE);
QuantityType<Length> qtFuelRange = QuantityType.valueOf(rangeFuel, lengthUnit);
updateChannel(CHANNEL_GROUP_RANGE, RANGE_FUEL, qtFuelRange, channelToBeUpdated);

So in two places I tell the system to use km, but still the value is converted to m. I could for sure configure each distance channel/item unit to km, but every user of the binding would have to do it.

What’s even worse is that a custom unit is removed from this channel:

	<channel-type id="estimated-fuel-l-100km-channel">
		<label>Estimated Fuel Consumption l/100km</label>
		<state pattern="%.2f l/100km" readOnly="true"/>

I tested the behavior in a fresh OH4 installation.

Do I miss a thing?


According to which documentation.

In OH 4 the whole way units are handled on Items has changed (see the “Changes in UoM” in Release openHAB 4.0.0 · openhab/openhab-distro · GitHub). Bindings no longer have the ability to dictate the units that an Item carries. I think they can still set the state pattern (as you show you are doing) but the actual state that the Item carries is defined either by the new unit metadata or, if that is not defined, by the system default, which is m for Number:Length.

Without unit defined and no override of the state description pattern on the Item, given the above XML, I would expect the Item’s state to be in m and where ever in MainUi that the state description pattern is used to show the state to be shown in km.

Thanks @rlkoshak , I hoped there would be a way to provide a default unit different to the system default so that not every user of the binding has to adjust the units manually…

I think I misunderstood this part

In some cases the system default unit may not be the most useful unit for a given quantity. For measuring precipitation km/h would be a quite uncommon unit, while mm/h would be the expected unit. You can set the unit metadata to a different unit to change the item’s unit

in combination with this one:

The state description pattern “%.1f %unit%” describes the value format as floating point with one decimal place and also the special placeholder for the unit

I thought replacing the %unit% with a different unit would result at least in a default state description if you create the item from the channel.

I think it should, but that is only going to be used for the display of the Item’s state. The actual Item’s state and value saved to persistence will be the one defined in the unit metadata, or the system default if the metadata isn’t defined.

So there might be something off going on here. I’m not sure. My understanding was that part UoM was left in place.

Ok maybe I’ll create a defect for that…

just for completeness: I got the state handling working fine with my code. The problem is that in the items overview the raw value is shown, so you don’t recognize that there is a different state shown in the UI.

1 Like

Did you open a defect for this topic. I would vote for +1.

I’ve the same problem. State pattern helps for display item state e.g. 100 km but in oh-cahrts still 100.000 m is displayed. I want to set the unit in binding otherwiese user needs to correct them after thing creation manually.

Do I understand it correctly that you want to enforce the unit of an item?

Because that makes no sense and actually would be harmful.
The metadata unit describes how the value is reported through the RestAPI and is stored in persistence.
I get that km might be correct for most of the users but this is something very user specific and should be done by everyone manually because of the implications.

The user has to create the item anyway so it’s easy to

  • set the correct unit metadata
  • set the correct state description

The user can create the equipment just by selecting all channels of the thing and then has to edit all items where the unit doesn’t fit. And if you consider the distance of a car it just doesn’t make sense to show it in m or ft. If any user really wants that he still can change the unit of the item manually.
IMHO there should be an additional section in the XML configuration like the one of configuring the state. That would be no breaking change and would bring at least for the car binding a lot of benefit.

Because it’s relevant, there is also a PR right now which adds unit as a field in all the places in MainUI where I an Item is created which should make this part a little more user friendly. They can set the unit before the Item is created instead of needing to go back and change it after the fact.

For users that use .items files it’s no burden to add unit metadata when the Item is created.

With this PR MainUI users will also be able to see the default unit and change it prior to the creation of the Item.


Perfect. This was part of the original RFC but must have gotten lost.
Even better that it’s finally added and a huge gain in usability. :+1: