Thing definition .xml - Categories

[pgfeller]

Hi all,

I start a discussion as proposed by @florian-h05 in the discussion of PR 16516. openHAB made huge improvements in the last years in terms of look & feel as well as usability. As it is a modular and flexible system a some complexity is unavoidable. To improve usability for new users and to make openHAB more popular one of my ideas of the implementation/port of the Hue Play HDMI Sync Box binding was, that creating the items from the (automatically) discovered thing will create a nice representation of the device in the semantic model (structure and icons).

So that this is basically a "one click" operation.

During the implementation I wondered, if a revision/enhancement of .xsd - or clarification regarding the Categories field would be beneficial.

The field is currently defined like this:

Categories are used to provide meta information about Things. Thing categories describe how the physical device looks like. UIs can use this information e.g. to render icons. The available categories correspond with the available icons of the classic iconset ...

To make the device representation more appealing I used icons from the Material Design Icons:

Commit 9a4889bd46e81c52f2bda6a94629a37b2afa7e6e

Currently the available categories are defined by the classic icon set; and there's a tight coupling between the visual representation and the category. The icons are a matter of taste of course - but in my opinion the types should not be matched directly to the icons anymore; as with the IconProvider mechanism it would be possible to support different icon sets depending on the users taste - and the definition would be an abstract category that would be resolved by the icon provider selected.

Of course I would prefer a more modern default icon provider for the Main UI - but that's my personal taste.

The supported categories could be defined in the .xsd as well, to have consistency.

If the schema is touched another thing could be considered; the semantic information could be included in a more intuitive way (also with defined types) for things. At the moment the semantic information is provided using tags: SemanticTags.csv. I would prefer defined types in the schema as well to make it easier for binding developers to create a consistent model (and to make it easier and more common, that this information is included in the bindings).

➡️ What is the opinion of the maintainers on this topic? Would it make sense to discuss this to elaborate a revision of the thing definition to decouple the category from the icons and update the schema with a type providing the available categories?

I also propose to start a 2nd discussion about if the current way of including semantic info with tags could/should be improved - or if that has no priority. To keep the changes small I propose to start with the categories - and to follow up with a discussion on semantic representation later.

As developer and user of bindings the information provided in the UI helps a lot and it is a far better experience if the semantic model and look needs less manual work.

with kind regards,
Patrik

[florian-h05]

Hi @pgfeller,

thanks for putting this up here.
I support the idea of decoupling the categories from the classic icon set, and would propose to rather have the UI define a mapping from categories to icons from different icon sets.
FYI this IMO should be done inside the UI from a architectural POV as the UI is the one presenting that information, and the F7 and Material Icon Sets are included into the UI.
The UI can then provide a selection for the user which icon set to use when creating the Items from the Thing.

Your proposal of decoupling categories and classic icons would also allow adding new categories much easier, e.g. as requested in openhab/openhab-core#4383.

I am not sure if this change requires a revision of the Thing XML at all or if the actual code changes are UI only. However the general change should be discussed among all maintainers.

Wrt to the semantic model, I personally would prefer to discuss that separately (and I haven’t though about that yet).

Pulling in @openhab/maintainers — please let us know what you think.

[rkoshak]

One thing to mention is currently when using a non-OH icon for the category, there is no control over the color. You basically get nothing but black icons.

I'm pretty sure that if you go down that path, the first thing users are going to ask for is the ability to set the color of the category icons. I'm not saying then have to be dynamic and adjust to the Item's state (though that would be cool if we could support an expression to control the icon and the color at the category level). I'm not sure if that makes sense to be a different follow on issue or if it should be wrapped up with this.

At the moment the semantic information is provided using tags: SemanticTags.csv. I would prefer defined types in the schema as well to make it easier for binding developers to create a consistent model (and to make it easier and more common, that this information is included in the bindings).

Isn't there an API endpoint now that populates the semantic tags? We've had the ability to define custom tags for some time now and I'm pretty sure that the selection gets populated from the REST endpoint, not the csv file now.

Beyond that, I have alarm bells going off in my head at the thought of bindings pushing semantic models on the users. But that's a discussion for another issue per @florian-h05 above. I just wanted to point out that with the ability to define new semantic tags neither the current csv nor moving them to the XSD is going to capture user's custom defined semantic tags.

[ccutrer]

One thing to mention is currently when using a non-OH icon for the category, there is no control over the color.

Sitemaps actually support defining a color for the icon (and conditionally, based on state): https://www.openhab.org/docs/ui/sitemaps.html#label-value-and-icon-colors. It definitely works in the iOS app, at least for Iconify icons (which is how iOS implements both F7 and Material icons) and the web based BasicUI. I don't use MainUI outside of admin tasks, so can't say if there is a similar thing to use there.

But that's a discussion for another issue

#1692 (and I reply specifically to this comment there)

Overall, I think that "category" is way too confusing. I think its original intent was similar to what the semantic model grew up to be, but was very limited because it had no structure, and quickly became tightly coupled to the classic icon set, so in effect became effectively "icon" rather than "category". I would agree wholeheartedly with either removing "category" completely (especially as provided by bindings), or redefine more explicitly to be "this is icon", but given the now prevalence of more icon providers, not limiting it to the classic icon set. While I think having a user defined mapping of "this is what a binding provides" to "this the icon I personally prefer to use" seems nice on the surface, I worry that it would not actually be useful due to soooo many different opinions, users should just manually change the icon (category) on items when they create them. For example, even if I have bindings providing "lightbulb" icon, I would usually customize it anyway to show a more specific icon - a lamp, a downlight, multiple downlights, multiple generic bulbs, an LED strip, etc. Same with fan - is it some kind of HVAC/climate device, a ceiling fan, a box fan? Outside of those most common categories which have a billion small differences that most bindings won't be aware of, the number of devices one has would be relatively small. I dunno though, because other less common device types will probably be more sure of what kind of thing they air - there's really only one way to describe a CO2 sensor, and if you have 6 of them, it would be nice to set the icon for all of them at once.

[kaikreuzer]

FYI this IMO should be done inside the UI from a architectural POV as the UI is the one presenting that information, and the F7 and Material Icon Sets are included into the UI.

I agree with @florian-h05 - this would stay in line of the idea of the category field as per its definition; It is a hint to the UI, while the UI can decide how to eventually render it.

The category was never meant to carry semantics; it should really just categorize the thing wrt its device type. Since the name "thing type" was already defined (in a very fine-granular way that makes thing types even specific for a certain add-on), the category is supposed to be what others would call a "device type" - see e.g. the Matter device types as an example. Such lists are usually constrained and not very excessive. So it should be fine for the UI to carry a mapping of those for the icon set that the user has chosen.