Naming convention for items and labels

Tags: #<Tag:0x00007fc903442978>

Hi everybody,

in this topic I want to ask for some guidance regarding item names and item labels respective to Openhab 3.

Item names
In Openhab 2 I used the following naming convention.

  • Category_Room_UniqueDevice_Function for “normal items”
  • g_Room_Function for group items

The room was added to all items that I have in my home. Honestly I was a bit lazy with groups for rooms, which means I didnt use them at all.

As the model in Openhab 3 uses groups very structured for rooms and equipments, Im thinking if it makes sense to change the naming convention right now.
The location of an item is clearly defined by the group. Would you continue having the room available in the item name and additionally by groups or would you define the location just in one place (the group)?

Regarding group names it could make sense to represent the kind of group. Instead of just using the prefix “g_”, the information if its a location or equipment could be added. “gL_” or “gE_”

Item labels
Basically there are two options. Either the label describes the device + location + function (independently of the order) or just the function as the device and location is defined using groups.
Option 1: Hue lightstip livingroom On/Off
Option 2: On/Off

I know the lable can be overwritten depending on where I am on the page. However I would like to know what option you prefer and why.

No but I wouldn’t have used that approach in the first place. But in OH 3 in particular, there is even less benefit to including the location in the Item name as it duplicates information that is stored elsewhere. The only exception to that though is if you need something to make the Item name unique and the room is about all you have to do so. For example, I do include the room as part of the names for my Chromecast Items as the room they are in is the only thing that makes them distinct from the other Chromecasts.

I used to do that sort of thing. I don’t even use the “g” prefix any more. It doesn’t really do anything for me. I get no practical benefit from that. I will use a plural noun as part of the Group name though which I suppose is a different convention. So far in OH 3, it’s usually pretty apparent based on the context and label which Items are Groups and which ones are not.

Based on the name of the Group it should be apparent whether or not the Group is a Location or an Equipment. I could see using some other convention for Groups that are not part of the model. Maybe that’s a good place to use the “g” prefix. But I’m not sure what benefit that has.

As someone who used to have a very strict and well defined naming convention for Items, I’ve found over time that while it feels good to have everything nice and standardized, sticking to the standard provided no practical benefit and did nothing but add complexity when naming Items. So I’ve abandoned almost all of them except:

  • Groups are plural nouns
  • Names should be meaningful to the human and not include the technology, only include the location where necessary to distinguish it from other similar Items
  • In cases where you have a sensor and actuator that it is hard to distinguish between the two (e.g. a garage door sensor and the garage door opener button) I’ll use the prefix v for the sensor (for “value”) and ‘a’ (for “actuator”). So far I’m about 300 Items in and I’ve only used this once so far

That’s it. Nothing more complex than that. I don’t add the room to every Item name because that’s represented in the model. I don’t include the function in the Item name because the name of the Item makes it apparent what function it provides.

If there’s a tl;dr here, strict naming conventions with all sorts of little letters to signal different things is not a replacement for using meaningful names and if you use meaningful names, all the stuff that the letters signify should be apparent.

Having said that, there is one naming convention approach I do recommend and thankfully it is what the Items created when adding Things and Equipment follow and that is to start the Item name with the same name as the Group that represents the Equipment followed by ‘_’ and then what the sensor or actuator is. By following that naming convention, you open up the opportunity to use Associated Items design pattern and an item prefix property in custom widgets (for example if you have a chromecast widget, you can define a property that includes the first part of the Item name and it will choose the right Items for all the various information presented in the widgets (now playing Image, player controls, volume, etc). You can’t do that easily if you prefix the Group names with all sorts of stuff.

As for the label. In OH 3 more so than in OH 2.5, the label is going to be what you are working with. It’s what gets searched for first. It’s how the Items are sorted in the list. So in this case I recommend choosing labels that help you uniquely identify that Item compared to all your other Items. If including the location helps with that include it. If not, why bother? What you want to avoid is having a bunch of Items labeled “Image”, one for each of the Chromecasts in your system. You need to add something to the label so you can easily distinguish between the Chromecast in the bedroom from the one in the den in the Item label.

But again, don’t go overboard. Don’t over specify yourself into a corner. Any standard you define needs to provide some benefit to you. If it doesn’t all it’s doing is causing you more work.

4 Likes

Thank you for your answer. Many helpful thoughts.

For now I will use the default names proposed by the UI “Equipment_Function” whereby the equipment includes the location of the device to make it unique.
The labels will include everything that is required to uniquely identify an item.

In general I will follow your recommendation and keep it as simple and possible.

1a) Items - Names
In OH2 for Items I used a naming convention of (<Floor>)_<Location>_<Device/Function>_(<Specification/Property>). The parts in () are optional and only used if needed for differentiation. E.g.

  • Garage_Light: Simple case where I have only one light source in a location or
  • MF_Kitchen_Light_Door_1_Brightness: I have 6 doors that emit light in my kitchen in the main floor and this is the first of them
  • Garden_Weathersensor_Humidity: A multisensor placed in the garden with humidity, rain, … readings

For me this makes it very easy to mentally map an item to something physical. Also it’s quite searchable and makes for easy to follow entries in the log.

So I’m going to keep it this way for OH3. The only thing to note here is that the <Location> part now exactly matches the Location Groups name (minus prefix, see below).

2a) Groups - Names
In OH2 I used to have groups for categories (g_Lights), utility functions (g_Persistence_Hourly), locations (g_MainFloor) and items that somehow are grouped together (g_Kitchen_Light_Doors). All shared the same g_ prefix.

For OH3 I changed this completely because of the new semantic model. I now have:

  • Groups of physical items: This is the only one identical to OH2 and starts with g_. Example: g_Kitchen_Light_Doors.
  • Groups that represent an Equipment. Those share the Items base name plus an e_ prefix. Example: e_MF_Kitchen_Light_Door_1. This group would contain MF_Kitchen_Light_Door_1_Switch and MF_Kitchen_Light_Door_1_Brightness.
  • Utility groups: Used for persistence or other utility functions like conversion of color from RBG to HSB. Those start with a u_ prefix and then a loose description like u_Persistence_Hourly or u_Convert_HSB_to_RGB.
  • Location groups for the semantic model locations. I initially wanted to prefix them with l_ for location but this was so hard to read and easy to mix up with a capital I that I settled with r_ (room) instead, even though it is not quite accurate as a location is a brouader description than a room. But anyways it’s easily readable now. Example: r_Estate, r_MainBuilding, r_MF (MainFloor), r_MF_Kitchen.

I feel quite happy with this approach because I can quickly see what the purpose of a group is. Especially with the new Equipment groups this comes in handy.

2a) Groups - Label

  • Equipment Groups: Description of the Equipment, without the room (“Ceiling Light” or “Light Door 1”).
  • Location Groups: "Description of the Location, e.g. “Main Floor” or “Kitchen”.
  • Utility Groups: Whatever you want, those are not displayed anywhere.
  • Groups of physical Items: Plural version of the items, this time with the location because in my usage they are not ordered into the semantic model, e.g. “Kitchen Light Doors Brightness”.

What I’m struggling with in OH3
As you might have noticed, I did not include a section for 1b) Items - Labels because I’m currently struggling with this. From my perspective (maybe shaped from my daily work as a programmer) a main goal in complex systems is to avoid redundancy as much as possible (also known as DRY - don’t repeat yourself).

For the most part I can see this working very well in openHAB3 and the MainUI:

  • Location(Building), e.g. “Main Building”
    • Location(Floor), e.g. “Main Floor”
      • Location(Room), e.g. “Kitchen”
        • Equipment, e.g. “Light Door 1”
          • Point, e.g. “On/Off” or “Brightness”

So the Item that is linked to the Channel would just be called “Brightness”. And this seems to perfectly fit with the automatically generated Location area in MainUI (excuse the german example, I’m too lazy to build an english one, but I think it’s easy enough to understand):

image

This seems to be very reasonable: Location and the parent of that Location are shown in the header, the Equipment is in the Group title and the actual points below that. All nice and clean, I love it. Especially on smaller devices (smartphone) where every unneccessary word on the screen makes it harder to read (and quite often is truncated otherwise) it is great.

But (you knew there was a but coming and it’s a rather big one :wink: ) almost all other places seem to not agree with this labeling convention:

MainUI Devices Area:

image

How should I know which room we are talking abour? “Light Door 1” might still give me a clue because I only have those in the kitchen, but I have lots of equipments called “Ceiling Light”. It’s try or error hitting the right one there.

This would be fixable by including the Location (and parent location?) in the header, e.g. “Leuchte Schranktür 1 (Kitchen > Main Floor)” for the example.

MainUI Properties area:

image

Here it it something different again. All clues to what Equipment this is part of and what room this is part of are missing. To make amends for this, the Item Name is included instead.

While this works (especially with neat item naming conventions like mine :wink: ) I feel like this is also a lost opportunity to really make use of the semantic model.The “Location / parent Location” and the “Equipment” information could (and should imho) be displayed instead of the item name.

Google Home integration:
For the Google Home integration, the Item’s Label is used as the name displayed in Google Home as well. So “Brightness” for my examlpe. That of course doesn’t make too much sense, especially when there are multiple “Brightness” in one room (my 6 Kitchen Door Lights for example).

Manual solution: To fix this, I can include an override name like [ name=“Kitchen Light Door 1” ] in the Google Home metadata and it’s working fine, even though it’s quite some additional work.

Automatic solution (not available): This could just be derived from the Equipment and Location instead, e.g. <Location> <Equipment> <Point> would result in an acceptable “Kitchen Light Door 1 Brightness”. Google filters the room name away anyways for most purposes and a custom name could still be given.

HomeKit integration
Same problem as above but worse because the binding does not accept an easy override for the name.

Manual solution: A rather complex override for the name does exist, but you need multiple Items and a Group for it, so it gets quite complicated and results in lots of items and rules for setting the Items values to the Name that should be displayed in HomeKit. Another approach would be a Proxy Item just for the sake of changing the display name in HomeKit. This would have to be synchronized with the “MainUI Item” then.

Automatic solution (not available): See Google Home section above.

Alternative approach
So this labeling convention seems to be very logical and works great with the Location tab (which is at least for me the one I think I will spend most time in) but poorly with everything else. So you might suggest the alternative of “cram everything into every Item label”. Then we end up with labels like “Main Floor Kitchen Light Door 1 Brightness” which is neither semantic nor easy to read:

image

On my 32" desktop it looks manageable (though not pretty and quite redundant) but on my smartphone it is literally unusable:

Question
How do you handle this? Is there some obvious flaw in my logic?

That’s why I suggest above that it’s the label that is more important to get unique than the Item name. For the most part, the Item name is only ever really used in rules. All the search functions in MainUI search the Labels as well as Item names so searching is the same.

You don’t necessarily have to put the location in every Item (though I do), but the equipment should definitely have the Location in the label. Though

That won’t work for the Properties tab though. The headings there are the Point tags, not Equipment or Location.

As with all things you can file an issue to request this feature, but I question how this could work in all cases. For example:

I wouldn’t want there to be a gray line with the location and equipment separating each and every one of those temperature sensors on my Properties tab. That would totally break up the visual and make it harder to quickly scan through them and compare them with each other.

Ultimately though, I’m not sure the UI in that part has the information necessary to navigate the Group membership to efficiently to discover the Equipment and Location it belongs to. For every Item displayed there would be two and maybe more API calls as the parent groups are pulled until you get to the Equipment and the Location. And what if there isn’t an Equipment or there isn’t a Location? In short, this would not be trivial to implement.

And as a work around, you can create default list widgets for each of your Items that includes the Equipment and Location as part of the widget., maybe in the footer.

This could be written up in a Rule pretty easily.

But ultimately, both Google and HomeKit integration precedes the adoption of the semantic model by quite some time. If you want them to take advantage of the semantic model you’ll have to file issues on each of those to request such a feature.

As I described above. I worry less about encoding everything in the Item names and I add just enough to the Item names to make each one unique and descriptive. I don’t use HomeKit and so far the labels have been enough to control what I want to through Google Assistant.

But I have also overridden the default list widgets for all my semantically tagged Items which gives me a uniform look and feel for them and allows me to make the icons and colors dynamic in ways that were never possible before.

At some point, I might remove the part of the label that is common in fact. For example, I don’t really need the “Temperature” part of those labels. The fact that it’s a temperature readings is encoded in the icon and the units after the current state. But it’s not important enough to me to make such a change right now.

1 Like

Thank you for the detailled reply, Rich!

So there is no “obvious solution” I’m missing but various workarounds, mostly duplicating the location information in the item name. I’ll think about this some more and then probably go with a combination of:

  • Create custom dashboards for the most needed functionality
  • Only use the Locations tab of the auto generated ones for now
  • Use custom Widgets with header and footer set manually for each item
  • File an issue against WebUI to improve on the “Equipment” and “Properties” tabs
  • File an issue against the HomeKit integration to support custom names. I think this one is due anyways because for some rooms Google Home and HomeKit use different default names (e.g. “Bad” vs “Badezimmer” in german) and so having one item to support all voice assistant results in one system getting left behind (e.g. HomeKit strips the room name from the Item when it is placed in that room. That obviously only works if it is identical, not “semantically near”).
  • Maybe also file an issue against the Alexa binding because it seems to be the same as HomeKit in this regard. But honestly I don’t care much about Alexa personally so that will be a low priority for me.

For every Item displayed there would be two and maybe more API calls as the parent groups are pulled until you get to the Equipment and the Location.

I think all the data is loaded at that stage because it is existent in the “Locations” tab obviously and switching between the “Locations”, “Equipment” and “Properties” tabs doesn’t result in requests against the backend. So it would “only” be using the existing data and display it in different / additional places.

And what if there isn’t an Equipment or there isn’t a Location? In short, this would not be trivial to implement.

Yes, that will need some though for a clean solution, but I think it’s possible. In the Issue I’ll try to get a grip on all those edge cases and show possible solutions.

I really do think that OH3 can do (even) better here, so if Yannick agrees with me that this is something that should be implemented I’ll also try to do the coding / PRs here.

1 Like

You’ll notice that when you mess around with expressions in custom widgets that you can’t access an Item’s list of parent Groups. You can, at least in the oh-repeater widget, access a Group’s members but you need to go the other direction to implement what you are after and it is not at all clear that that information is loaded and available in the namespace and in a way that is usable by the widgets.

NOTE: if you do go down the path of overriding list widgets, create them as a custom widget once and then apply them to each Item.

it is not at all clear that that information is loaded and available in the namespace and in a way that is usable by the widgets.

Well, the code is the truth (at least for software) so I’ll have a look at the code for this later. But I’m quite positive that the data is available at the places I’ve been talking about. Thanks for the reminder though!

NOTE: if you do go down the path of overriding list widgets, create them as a custom widget once and then apply them to each Item.

Sounds like a good idea. I’ve only started using widgets yesterday and have not yet found out how to do this, though. Any hint where to look? :slight_smile:

UIs - openHAB Community in general. For List widgets in particular Example Custom List Widgets, some simple oh-repeater examples A couple of simple oh-repeater examples and Oh-repeater with accordion slots (for using repeater in accordion widgets). There are tons and tons with more being posted every day of stand alone widgets.

But if you like DRY, oh-repeater is going to be your friend.

1 Like

Hi @eikowagenknecht,

I saw the same problems and thougt, that I did something wrong. :slight_smile:

Thanks for your insights!

Bye
HFM