Discussion about OpenHAB Item types

I don’t know if saying this another way will be helpful or cause more confusion but in case it’s helpful, here goes.

What I think is a source of confusion here is that you are assuming a much more direct connection between the physical device and that device’s representation in openHAB. In truth, the connection between the two has to go through at least three layers of abstraction.

  1. The connection between the physical device and openHAB’s binding for the device is defined by the API and is controlled by the device maker/technology. At this point we are dealing with ones and zeros transmitted over a wireless communications stack, or TCP/IP, etc. We are at the level of messages so at this first layer we are already a really long way away from a potentiometer. We are at the level of binary messages and hand shakes and acknowledgement messages and such. Given this, it is probably the rare dimmer device that cannot accept an ON or OFF message from the binding.

  2. The binding developer defines a Thing to represent everything that the binding allows one to do with that device to OH in a standard way. Things and Channels are themselves a layer of abstraction. They free the users of OH from needing to know anything about all that stuff happening at layer 1 so whether you are dealing with zwave or MQTT, you are dealing with a standardized interface, Things and Channels.

  3. The final layer is Items. Items are where you model your home automation and the individual Item types model the behaviors of a fixed set of ways to interact with these devices. A Switch is a binary control (ON/OFF). A Contact is a binary sensor(OPEN/CLOSED) but because it models a sensor you cannot send a command to a Contact. A Dimmer is a percent that can be increased, decreased, and turned ON and OFF. These are how these are the standard set of devices models that OH supports.

There is a whole lot of translation between abstraction layers going on to go from a click on your sitemap to a message getting sent to the device.

1 Like

Can I have a last try at explaining the Dimmer item in OH?

I think the bottom line is that the Dimmer item in OpenHAB serves the purpose of having a unified interface, such that both sitemaps and rules can control the dimmer in the same way regardless of whether the actual hardware dimmer is IHC, KNX, Z-wave or whichever other type.

So if there was a dimmer (hardware) that had a protocol with separate commands for on/off and brightness, the developer writing the binding should make a single OpenHAB dimmer channel.

Sending the ON or OFF commands to the Dimmer item would cause the binding to send the respective on/off command to the dimmer.

And setting the brightness to e.g. 75% would ensure the on/off state is on, and set the brightness. If the binding devloper instead created separate channels (Items) for on/off and brightness, then to turn on at 75% you may need to both set the on/off channel and also set the brightness.

Also, note how in this scenario, sending an ON command to the dimmer will only affect the on/off state, and hence the light would turn on at the level it was on last, before being turned off (maybe 75%). However, the Dimmer item in OpenHAB would report its state as 0% when the on/off state indicates off, regardless of the brightness state. And when the on/off channel is on it would report the brightness level for Dimmer item state.

After this long discussion, at least I have a much clearer understanding of what a Dimmer (in OpenHAB) is. Thank you @rlkoshak and @rossko57 for your persistence in trying to explain it to us all!

Now, would it be OK if I try to win this thread back to discussing new OpenHAB item types, instead of continuing discussing how Dimmers work in OH? :smile:

I must say that I like that concept. My main OpenHAB UI is still the classic (sitemap based) one, so my imagination of the possibilities might be somewhat limited.

Very interesting.

I agree, and I would add that some additional types can also make the rules more comprehensible.

As the discussion has been progressing, I have gotten more and more used to the thought of a Dimmer being an item type that has a state between 0 and 100. I still think a name like Percentage instead of Dimmer would be more logical, at least when it is not used to dim a light. Perhaps the benefit of changing Dimmer to Percentage in the existing code base is not worth the effort, and it would also break compatibility with other (e.g. un-official) bindings.

When I started this thread it was to discuss if some additional types were needed. After getting a better knowledge of the Dimmer item, perhaps that type is suficcient for many things. I still think that it would be possible to introduce the new Percentage type, which would be the more logical choice/name for a binding developer, if he is not controlling the brightness of a lamp.

In my opinion there is still a benefit of such a type (whether it is Dimmer or Percentage) over just using Number, because defining the range of 0-100 helps achieve compatibility. If we only had Number we could easily end up with one type of light dimmer using range 0-255 and one using 0-100.

Coming back to the Contact debate; I think the naming of these binary states (OPEN/CLOSED) is one of the things that is less obvious to many users of openhab. It is probably also the reason why many binding developers end up using Switch instead of Contact, because for instance an input like BoilerHeating makes much more sense if the state is ON/OFF instead of OPEN/CLOSED.

My point is exactly that I want the items to represent the objects in my home, such as a window or the furnace. It is just not so logical that all binary inputs are either OPEN or CLOSED.

But thank you for the pointer to documentation on map profiles. I will need to look into that, and see how far I can get down that road.

One solution (as previously mentioned) would be to have a boolean type, and the name of the channel or item would carry the meaning. I am not exactly sure how the rules DSL should be adapted to cover this (not entirely happy with “when FurnaceHeating changed to FALSE”, but I still find it better than “when FurnaceHeating changed to OPEN”).

Another (far more complicated) solution would be to have some named enum types, such that when defining a binary input, the states could be defined. For instance a window sensor could be OPEN/CLOSED, but a stove can be ON/OFF or a network can be CONNECTED/DISCONNECTED. For bindings where the binding developer knows what the channels designate, the stated could be defined by the binding. For more generic bindings, such as one simply handling a binary input, the names of the states should be defined in the Item definition.

I think such a system would make the rules more expressive and easier to understand, although I am aware that it might require a lot of effort and some will surely find that the effort outweights the benefits. I guess some of it can be obtained by having String items and converting the Contacts state to strings with a map function. I guess with a multi-core processor running a few GHz the cost of doing string operations when processing rules is not outrageous, but it just goes against my nature.

And just to not fuel that fire: I am aware that unless some developer finds these considerations nice and actually decides to take on the task of developing it, we are just having a discussion about some ideas which some may find useful and some may not think are of any benefit.

Wouldn’t a BoilerHeating Item more properly be a Switch anyway so OH can turn the boiler ON or OFF?

It may just be because it is Monday and I haven’t had my coffee yet this morning, but I’m struggling to imagine a case where ON/OFF makes the most sense and yet you have an Item that is just a sensor. Again, with the FurnaceHeating, wouldn’t you want this to be a Switch so you can control it?

That would be exceptionally awkward to use from Rules because at a minimum we would have to import those states to our Rules to use them. I’m not even sure how it would work for the UIs but it’s not going to be nice and clean because we would be going from a fixed set of predefined states to a world of dynamically defined types. Don’t forget, changes like these need to propagate to the Rules, Persistence, and the UIs/REST API. In my experience doing this adds an order of magnitude to the complexity of the code on similar systems I’ve worked on in the past. Maybe not so much for OH, I don’t know the code that well.

Even on a RPi 2, the cost of doing these operations using Strings compared to numbers or enums is unmeasurable in a home automation context. In fact, what your nature would push you towards, using primitives, is actually more expensive than using Objects in Rules DSL, at least in terms of parsing and compiling. Switching from primitive ints to Number in Rules DSL has cut minutes from the rules loading time for some users.

It’s not so much this but that even if it’s the best idea in the world nothing will come of it. So it becomes an academic discussion that has no impact.

I think the arguments are clear and the positions are well defined. If you think this is really important, go file an issue and convince the developers. A change like this, because it pretty much touches ALL of the repos, would probably need to go before the Architecture Counsel so you need to convince those developers as well. And as usual, the willingness to work the PR yourself will carry more weight than just a good idea.

Actually items don’t cut for some time apready. What was intended to counteract on Kai’s position of not adding more item types is item metadata.

The Alexa and Google home IO services use item metadata to combine primitive items, and to semantically recognise their real functionality. As we noticed in this thread, a Dimmer item can be anything, a temperature, a dim level, a volume. Other home automation frameworks have all those basic types. And on openhab we double the required work to setup something working: First the binding author need to break down a semantically well known type to an OH basic type and then the user need to “convert” that back to a semantically rich type by using item metadata.

It’s actually time to rethink item types and if someone comes up with a white paper, maybe also by comparing with other frameworks, we might be able to have richer items in OH3.

1 Like

As an electrician, a “contact” being “open or closed” makes perfect sense to me :wink: Although I understand that the same synonyms are found in many languages.

Maybe we should consider “flavours” or sub-varieties of basic Items.
Consider UoM; we can have type Number.
We can also have Number:Temperature - it’s still a Number but with some add-on units baggage.
It’s my understanding that bindings can “suggest” units when they offer updates to Number Items.

Using that as a vague model, let’s invent a flexible binary Item
Binary - commands TRUE/FALSE, states TRUE/FALSE
Binary:Switch - commands ON/OFF, states ON/OFF
Binary:Contact - read only , states OPEN/CLOSED
Binary:Run - commands STOP/GO, states RUNNING/STOPPED
Binary:Light - states LIGHT/DARK, but are we allowed commands or not?

Not very keen on the idea myself, seems to be just about words.

There may be more use for more complex Items.
RollerShutter: Pushbutton
The kind of roller that expects you to hold a button for movement
RollerShutter:StopGo
A roller that keeps moving until stopped.
RollerShutter:Preset
The kind of roller that expects you send a predefined position selection, a scene.

I think he is actually saying ON/OFF makes more sense rather then open/close when it´s a heater… But I believe he mean, that it´s a contact, and then it will report open/closed if he set it up as a contact… And then it would make no sense.

I havn´t got the white paper, but my opinion is:
If items is defined from the idea/use of the device it is linked to, most people would be able to get the idea just by using common sense. At least for more common devices in a home automation system.

Sure, this is much about words and language.
But no matter where you are ind the world, no matter what language you speak, you probably know, what function a device have. Ie… If it´s a door/window, you know, no matter from where you are, that this devices can either be opened or they can be closed.

Problem is today, openhab needs a item definition ofcouse. But in some cases depending on which interface/binding your using, its on/off. Another binding is open/close. Some devices with the same interface don´t arent even equal, like z-wave devices.

Now what if the item type was just plain and simple - Window or Door type?
And for automatic window it could be a simple as - AutomaticWindow - Which btw could be a controled by a dimmer, if it handles on/off :slight_smile:
The same goes for a simple light… It´s on/off… Well, the item could just be as simple as - Light or Lighting.
If it´s a dimmable light, again,plain and simple - DimmLigthing

This way the users dont have to think that hard. And the user certainly dont have to wonder, how come a contact sometimes is defined as a contact, and other times its a switch.

I agree, the nomenclature throws a lot of new users. Perhaps is even better then a glossary is a more thorough explanation of OpenHAB’s specific nomenclature in the concepts.
Folks totally don’t get that a dimmer item can be a light dimmer or a volume knob. (or any number of other things) People are constantly bamboozled by the fact a color item can be a switch item.

If a system is bad, why keeping it and building a bunch of workarounds around it.
If a ton of documentation is necessary because item types have bad names, I mean seriously. Just rename the item types.

This is open source. Either the mediocracy like voted opinion wins, or a better fork appears.

I personally agree that OHs item types are not well thought through, so I’d be more than happy to see this rationalised… However, this should be in OH3 - not OH2. At the moment, we need some stability as there are two many significant/breaking changes going on right now :sunglasses:

That’s fine, let’s do the simplest case. (and yep an OH3 topic)

type Binary_Sensor
A read only Item. People don’t like state On/Off for doors, or Open/Closed for boiler operating indicator, or True/False for windows. 0/1 brings challenges too, 0 implies off or not-something so that will not do. It would in any case get confused with real numeric values.
We’d better have states X and Y to prevent confusion, so that it deliberately conveys no particular association at all.
That does leave some room for confusion with strings of course, but we’re not in a position to invent new characters I guess.

type Binary_Actor
A read/write Item.
It’s an interesting debate whether this should have the same states as its partner sensor. It does seem reasonable to treat an ‘actor’ as an enhancement of the ‘sensor’, so let’s assume X and Y is okay here too.
There arises endless confusion between commands and states, so these ought to be different here. We could make sure to avoid confusion using A and B, but it would be even more confusing to hide any connection between whether A is expecting result X or Y.
Maybe actX and actY would be suitable; obviously not the same as state but clearly related, with an expected outcome.

For myself, I’m not very convinced about having both types - the read-only Contact (binary_sensor) type is a real oddball unless you planned also to introduce read only numerics etc. I’ve not seen any issue arising from lack of read-only numbers for e.g. temperature sensor, can’t see the need?
Bin Contact type and keep Switch with ON/OFF. People who can’t handle the abstraction of “this switch is ON means my door is closed” are going to really struggle with the rest of openHAB.

I would just call it binary. It is not what the users sees anyway, only interesting for a binding developer and the runtime. Binary is unfortunately conflicting with “binary data” like images. Internally that is already called binary.

What I have in mind is in line with Yannicks vision. The binding author MUST assign semantics to a channel, according to the Brick Schema (http://brickschema.org/structure/). Instead of defining an item type semantic tags for Point, Equipment, Location, and MeasurementProperty (and some other meta data like number limits, read-only etc) are given. The value type (boolean, number, string, binary) can actually be derived from those tags. If no tag is matching, a binding author may assign raw types (boolean, number, string, binary) as last resort.

An item may override those suggested tags.

Because those tags are hierarchically organised, a UI can always render fallbacks. So if no “Heat-Pump-Valve” specific widget is existing, and also no “Valve” one, the widget for Number will be rendered. But if a specific widget is available the user will get the best possible experience out of the box. No additional documentation necessary.

1 Like

Afaik as soon as OH 2.5 is out (which should be imminent), the 3.0 cycle starts. So that is soonish and it makes sense to reason about those topics.

Okay, I follow that. Let’s say the device is a zwave contact on a door … it identifies itself to the binding, which knows the (main) data is about a binary open/closed sensor. I’m assuming this zwave device doesn’t report if its fitted to a door or window or catflap. Other devices might be more specific, say if we were getting this from an intruder alarm system. But here, the binding makes available a channel of “contact” type, the general case, How does it represent the status to the channel/Item, as open/closed? Is this a bit like existing numbers with units, we get a true-false payload and a unit of open-closed? EDIT - enumeration is I think the word I was groping for.

open/closed seems to cause a lot of gnashing of teeth in posts above. Let’s make it a fire alarm sensor. We get a type of “fire_alarm” because we don’t know more specific (e.g. smoke alarm, heat detector) but we do know its not a door. We get a payload of … ? true/false with “units” of okay/fire? i.e. different from a panic button with okay/alarm.

I’m trying to imagine how to deal with that in rules. I guess the type and type hierarchy can be examined. And the payload, expressed with or without the “units”

Absolutely- I completely agree, and the discussion is right. I’d just like to ensure these changes go into OH3 and try and get OH2 back to a stable condition as all the recent breaking changes have really made for a lot of instability that should have been reserved for a major release.

1 Like

Perhaps, but that is not for the user nor the binding developer to decide. Maybe there is a general enable switch, but usually the boiler would have a setpoint (possibly controlled from OH) which would be compared to the measured temperature (which may also be available to OH), yet it would be nice to know when the heater is actually on.

And it is available in the current implementation of OH, which is also a big plus :grinning:
I still think we are having a good discussion here, and I just hope that some of it is taken into consideration for OH3. Some of the other suggestions in this thread may very well be even better than mine. The whole point of the discussion is to get people to explain their ideas, and see if we can come up with something better than what we have so far.

I agree. And the impact is both on the different user interfaces as well as making the rules less expressive.

Exactly. Using the item name Dimmer makes it easy for people to understand when they have a dimmer, but also using it to control something different (like volume or window position) is confusing to people not familiar with what a Dimmer is in OH. Since Dimmer is a familiar word, it is very natural to think you know what it means. The long discussion about the Dimmer earlier in this thread shows that there are many different thoughts about what it is (and it appears that a lot of the confusion in this discussion is actually caused by the clashing of nomenclature).

I think this is a good point. Maybe instead of having separate types, the items could be tagged as read-only. Then the GUI rendering it would know if this item should have a control to manipulate it, or just show the current state.

Very interesting.

Yes, I think that will be needed for more generic interfaces/bindings, where the binding author has no chance of describing what the Item represents, but only what it is (for instance a binary input sensor). The user would add tags to signify that this sensor is actually a window contact.

It’s a tempting idea, but thinking through my practical installation, I want occasionally to be able to “force” a value e.g fake a temperature to test functions. Only an occasional need but difficult to manage with true read only.
It’s easy enough to not write to something by choice, we’ve all been doing that so far.
Maybe much depends on “read only, but by who?”
Perhaps we mean an “uncommandable” Item, which is rather more like the current Contact type.

I’ll object to UI part only, that how you choose to show it is not an Item property (though of course you should have defaults). e.g. I want this Item r/w for an admin user and r/o for ordinary user. This is one of the clever parts of existing sitemap, choice of widget.

Good points.

What do we really mean by read-only? I was thinking mostly about whether the default in the UI should show a control to manipulate it. Since the default widget for a Number item does not allow manipulation of the number value, I think we currently only have a similar case for Switch/Contact?

When a binding developer decides that something is an input (read-only, or whatever we should call it), it conveys the fact that manipulating the Item (through whatever means) will not cause the binding to send this to the actual device, simply because that is not possible. And therefore it also makes sense that whichever GUI is used will not by default show a control to manipulate it.

In cases like the one you describe above (forcing a value on an item), it could be allowed, but it is important that the user knows that he/she is manipulating the Item state, not the actual device.

With richer Item types or metadata/tags as others have suggested, the default GUI widget for setting the temperature (setpoint) of my floor heating would of course have some controls allowing me to change the setpoint, whereas the default widget for showing the current room temperature would only show the number. Today those items are both Numbers, and I have to decide in the sitemap which widget should be used.

Yehbut … in OH2 at least, Items may have multiple bindings and link to both “out” and “in” channels. One binding’s read-only designation should not limit UI, rules, or other bindings.

Since we are on the topic of names of things, it is also one of the sources of confusion. I’m frequently helping people who assume that you can only use a Switch element to show a Switch Item on the sitemap.

Again, I’m not advocating for a change because I still do not necessarily see the disruption that would be created being worth the improvement in clarity in these cases to go and rename everything. But it would help avoid confusion if different names were used for sitemap elements and Item types. I think HABPanel does a good job in this regard.

3 Likes