Structured /Logical naming for thing / items

Setup, Configuration and Use Items & Sitemaps
,
1

Hi,

I wonder how everyone else is structuring the naming of things, but mostly the items.
I see that in my configuration I am missing the structure and/or logic with naming items.
I don’t seem to be able to get it right so it makes sense. I currently use e.g. GF and FF for starting the names for things on each floor. e.g GF_lights_dinnerTable, but this does not separate the technology used (e.g. zigbee, zwave), also I don’t have any logic currently for separating items which are linked to real physical things, or e.g. test items for scripts, or items linked to e.g. weather bindings…

How do you all structure this and add logic to naming of things and/or items?

Thank you!

2

One of the significant improvements in OH3 is that with the MainUI, item names have been devalued to a certain extent because for so many aspects of UI configuration you can sort/search by the more sensible item label instead. On the other hand, especially if you are writing a lot of rules/scripts there’s much to be said for having at least a simple nomenclature that prevents you from having to lookup odd names and potentially makes reading the scripts easier. But I certainly wouldn’t go beyond something fairly simple.

For my case, every item has a prefix for the family of item it belongs to, a main descriptor, and, if relevant, a suffix for the particular item use.

Prefix examples would be things like Switch_, Speaker_, Remote_, etc., but this extends beyond physical devices. It includes OH proxy items like Auto_ for items related strictly to automation rules or Google_ for items specific to my google assistant configuration. It also includes items that derive solely from the semantic model, for example Location_ and Person_ (I use semantic model “locations” for individuals in the house for modeling of personal electronics which, obviously, have no fixed location).

Main descriptors are camelcase word series that give a rough location (if appropriate) and other identification. For example, PatioLight or LivingRoomFan.

Most model equipment stop at the prefix and the descriptor, but if the item is a semantic point or other action type item, then suffixes give basic function of the item. So common ones are _OnOff if it’s a simple switch or _Brightness. Less obvious ones might be _TS if it is a timestamp or _Count for groups that have an aggregate count state of members.

Put all together each item looks something like this: Switch_MasterBedroomFanLight_OnOff or Sensor_Garage is the equipment item for the ZWave sensor in the garage with various components being Sensor_Garage_Motion or Sensor_Garage_Temperature etc.

3

First I would recommend reading the many similar posts that have been created on this topic.

I strongly am of the opinion that Items should never refer to the technology. That’s the business of the Things. One of the whole points of Items is to abstract from that. Who cares if it’s a zwave switch or a shelly switch? You’ll just sendCommand(ON) to turn it ON either way. Leave the technology at the Things, they don’t add anything at the Item level.

Again, who cares? It doesn’t matter what it’s linked to. What matters is what the Item represents. Maybe it’s a proxy Item that hides a bunch of complicated rules to translate a bunch of stuff from several different Items. That’s fine but as far as everything that uses that Item is concerned, it’s a Switch Item that controls the living room lamp. So call it “LivingRoom_Lamp”.

I’ll second JustinG’s suggestion, keep the naming scheme simple. Use meaningful names. And don’t add anything to the name that doesn’t need to be there. Include just enough to make the Item name unique and understandable to you.

If you have a group of Items that are related to each other, for example a Contact indicating when a door is open and a DateTime that keeps track of the last time the door was opened, use a naming scheme that lets you construct the name of the associated Item using the name of the triggering Item.

For example, when the door opens, in a Rules DSL rule I can use

var dtItemName = triggeringItemName +"_LastOpened"

if the Item’s names are FrontDoor and FrontDoor_LastOpened.

If adding prefixes so that you know that a given Item is on the first floor, or is an Item used only be Rules or something like that, go for it. But do so because it adds value to you, not just because it feels more organized. In my considerable experience, as someone who used to have such a strict and complicated naming scheme that I had a table in a comment at the top of one of my .items files to I could interpret and pick appropriate names for my Items at one point, it’s just not worth the effort.

KISS is the way to go and don’t try to preemptively solve theoretical problems. Use a naming scheme that addresses actual problems you’ve had with your Item naming up to this point. Don’t try to solve problems you may not even have with the naming scheme because ultimately you will tie your hands later on.

So my naming scheme is as follows:

  1. Use a meaningful and unique root name; all Items associated with a given device will use this root name
  2. if there is more than one Item associated with a device, use an _ and a suffix that provides a meaningful name for that Item
  3. the Equipment Group Item will be named with the root name
  4. in rare cases I’ll need to distinguish between an actuator and a value, for example the Contact that tells me the garage door is OPEN/CLOSED and a Switch that lets me command the garage door to open or close. In these cases I will prepend a to the Item name for the actuator and v for the sensor.
  5. note that a device is not limited to a single Thing; e.g. I might use a Shelly Binding Thing to control a light and the Network binding to tell me if the Shelly device is online, all part of the same equipment.

1, 2 and 3 make it easy to find Items in a search, pin them in the developer sidebar, and use the Associated Item design pattern. It’s also how “Create Equipment from Thing” likes to name things.

Some example Item names:

Item Semantic Tag(s) Type Technology
Backdoor Backdoor Equipment Group
BackdoorDeadbolt Lock Equipment Group, member of Backdoor
BackdoorDeadbolt_AlarmRaw The raw JSON messages Zwave
BackdoorDeadbolt_BatteryLevel LowBattery, Power Number:Dimensionless Zwave
BackdoorDeadbolt_DoorLock Switch Zwave
Backdoor_Sensor OpenState, Opening Contact None, proxy Item that gets the debounced Raw Item’s state via a rule
Backdoor_Sensor_Raw Contact MQTT
BackdoorCamera Camera Equipment Group
BackdoorCamera_Image Status Image IPCamera

Things to notice:

  • All the Item names are clear
  • All the Item names are constructible given any one of the other Item’s names
  • Not all Items are in the semantic model
  • Not all the Items are populated from a single Thing
  • There is nothing in the Item name that tells you what technology it uses and there is only enough of the location to distinguish this set of Items from the other exterior doors
  • I don’t include any information in the Item name that can be found out somewhere else (e.g. Item type, what it’s linked to, which floor or room it’s in, etc.)

Finally, notice I didn’t talk about Things at all. For manually created Things, I’ll usually change the randomly generated part of the Thing ID with something meaningful. In all other cases the Thing ID is derived from the manually created Bridge Things anyway and the ID is fixed during auto discovery, or I use something very short and meaningful (e.g. in MQTT binding Generic MQTT Thing). Except in cases where an Action is referenced, or a rule is triggered, the Thing IDs are only used when linking to an Item.

1 Like