Item Inventory and Naming

[Will]

Here are a few thoughts and things I would love to have known when I started with Z-Wave back in 2016.

Forget those ids

First of all, don’t focus on the node ids. Sure it is nice to have nice numbers but those will end up changing, just accept it and don’t get used to the id

If you reset a device, the id will change.
If you exclude/include, the id will change.
If you replace a damaged device, unless you go thru the “replace failed” procedure, the id will change.

Keep “inventory”

I would strongly suggest naming/marking your devices without any meaning of room, location, prupose. Something neutral that will never change.

I personally now mark each z-wave device with ZWXXX where XXX is a unique number. I also mark ZBYYY for ZigBee. I do that instead of marking then with something like “Window Bathroom” because you will end up recylcing devices and sensors. Not to mention that some devices will die and will replaced and if you move out, your will rework it all.

In my .items files, I add a comment with the UID (ie ZW001), and the brand / model number, it helps finding items again.
The rest is not required since the item itself describes: the purpose and the node id.

So you may start with ZW001 being the main door sensor … until a new cool sensor comes up, so you will then use your new ZW047 as main door sensor and recycle your ZW001 as a mailbox sensor… You get the idea.

Item names

What about Item names ?
I found a few posts related to naming and I think, as a beginner, it is worth your time thinking about it and not jumping heads down…

• Naming convention - #3 by HomeAutomation
• Naming convention question - #2 by hmerk
• Naming convention for items and labels

While the OH VScode extension provides useful unique item names, I think you should NOT be using those and edit them rigth away, before your save the file and persistence kicks in…

The names look like BoschDishwasherXXXXXXXXXXXXXXXXXXPowerState or ZWaveNode040FGMS001MotionSensorFibEyeOfficeAlarmMotion for a z-wave sensor for instance.

Not only those names are very long but also rather unreadable and not very useful for your “next steps”.

You may think that naming does not matter and OH makes it easy to rename items. A little search/replace to make sure your rename is done eveywhere, including the rules and everything is fine right ? Well no…

If you use persistence, if you want to use charts, etc… having better names and most importantly a convention, will help you a lot.
I went thru the pain of renaming and you probably want to avoid that.

I would argue that no convention is ideal and it is a matter of choice. So you don’t need to follow “mine” and I would love to hear how YOU do but the most important is that you have a “standard” and follow it.

Here is how my items are named:

• Office_Window_Right__SensorDoor
• Bathroom_Door_Blue__SensorDoor

More important than to see what this name is made of, I would recommend seeing what it is NOT made of:

• no node id
• no brand / model name (most of the time)

You may notice that there is no node id in there, there are some reasons for that. Mainly because ids will change and you do not want to have to rename all the time.
I also do not include the brand, model name since those may also change over time.

My “rule”:

<room>_<what>_<where>__<type>

I find this kind of naming also very useful when it comes to writing rules and using intellisense.
You can then think down:

• room
• what
• where
• type

The item name is really something to try to get right the first time.
The rest of an item can always be rather easily changed.

I hope that helps and I would love to hear alternative solutions.

[rlkoshak (Rich Koshak)]

@Will

The names look like BoschDishwasherXXXXXXXXXXXXXXXXXXPowerState or ZWaveNode040FGMS001MotionSensorFibEyeOfficeAlarmMotion for a z-wave sensor for instance.

This is one area where using managed Items makes things easier. When you use “add equipment to model” from the Thing’s Channels page or the Model page, you can chose a Location, name the Equipment, and then the Items become <EquipmentName>_<ChannelName>. All that hard to read technology specific stuff never makes it into the Item name in the first place.

@Will

You may think that naming does not matter and OH makes it easy to rename items.

This is most emphatically not the case. You actually cannot rename an Item. You can only delete and recreate a new Item with a different name. That’s why the connection to persistence gets lost and why you have to do the find and replace to change it everywhere it’s used.

One note on using .items files. Every time a .items file is unloaded all the Items defined by that file get deleted. Then when a .items file is loaded all the Items in that file are recreated anew. So it may seem like you are renaming the Item but in truth, you are deleting and recreating.

I just want to emphasize this as it helps make your point even stronger and it explains why there’s no “rename” option in the UI.

@Will

Here is how my items are named:

• Office_Window_Right__SensorDoor
• Bathroom_Door_Blue__SensorDoor

These are good Item names. I like that they are clear what they represent from the human’s perspective. Personally, I find your rule too prescriptive but it needs to work for you, not me. Even were I using .items files I’d probably call these: Office_RightWindow_Sensor and Bathroom_BlueDoor_Sensor or maybe even leave the “Sensor” part off. It’s pretty clear that the Item represents a sensor through other clues (e.g. Item type is Contact, State Description pattern is read only, those things only have sensors, semantic tags, etc.).

@Will

The item name is really something to try to get right the first time.

I’ll counter this somewhat with managed Items and configs. In MainUI, the name of the Item is somewhat suppressed in favor of it’s label. You can even toggle it so that you see and use the label of Items in Blockly rules code as opposed to the Item name. Given this, the name of the Items really becomes somewhat less important and therefore not as big a deal if you get it “wrong” or need to change it later. Labels can be changed.

Here are some screen shots to illustrate what I mean:

On the Items Page

The Item name is lighter in smaller print (e.g. vRichPresence).

On the model page you don’t even see the Item name by default unless you click on an individual Item.

Though there is a toggle to show the Item name if you need it.

When selecting Item(s) for:

• Group membership
• Widget
• Rule triggers, simple Item conditions, simple Item Actions, Blockly

The developer sidebar also emphasizes the label over the name. Clicking the copy icon copies the Item name though.

Over time, I’ve moved things around and renamed stuff and I do not always update the names of my Items. For example:

The Item name is “norns” but the label now reads “huginn”. This is because I moved this over to a different host with a different host name. But because I almost never need to see or use the Item name directly, I’ve not bothered to rename the Item. Doing so is more trouble than it’s worth.

It is definitely more important to get the Item names right when using .items files for sure as the Item name is much more forward. But if one is using managed Items, the pressure is off quite a bit. When you use the tools built around the semantic model to create the Items in the first place you’ll get reasonable names for the Items to start with and even if you get it wrong or need to change it later, it’s not that big of a deal because the number of places where you’ll actually need to use that Item name is greatly reduced in managed configs. In the worst case, you’d search for the Item in the developer sidebar and copy/paste the name if you have to use it by name somewhere.

@Will

I would love to hear how YOU do but the most important is that you have a “standard” and follow it.

I used to have a very elaborate standard with little prefixes to denote whether an Item is an actuator or a sensor value or a Group and a tiered set of segments similar to what you describe. And I still have some Items that follow these conventions (e.g. vRichPresence has the “v” in front to denote it’s a sensor value as opposed to an actuator).

Now my rules for Item naming are pretty basic:

• Groups that are not part of the semantic model are named such that it’s clear it represents a Group of Items or the rollup of a bunch of Items. For example: AllLights, MinIndoorHumidity, SensorsStatuses, AllBatteries, etc.
• <Equipment Name>_<Channel Name> for Items linked to Channels. Basically go with the flow from “add equipment to model”.
• However, I change the Item labels to include the Location (where applicable) and the Channel Name. That way, when I see a list of Items by their labels, I don’t have 20 “Temperature” Items that I need to choose from. I immediately know what location each Item represents. This helps distinguish between similar Items on the Properties tab of the Overview Page.
• If something else needs to be added to the Item to denote important information (e.g. to make it easier to find in the developer sidebar) I use tags.

For completeness, here’s a typical “add equipment to model” form.

First choose the Location and create the Equipment.

Further down select the Items you want to create Items for and set the properties for each Item as needed.

tl;dr, Your needs for Item naming change when using managed Items opposed to .items files and you have a little more flexibility in Item names when using managed Items so that getting it right isn’t as important.