OH3: Best practice item naming?

Max_G · March 18, 2024, 12:53am

I understand this is a can of worms

Over the years of using OH item naming has evolved or rather bastardised… mainly based on what seemed better based on examples code I have seen on OH from (what I deemed) experienced programmers.

One inconsitent example:

["ZevaAmpRemain","400.0"]
["Zeva_CellSetRaw","302,3427,3431,3441,3427"]
["ZevaCellVolt1_Chart_Period","1"]
["ZevaCellVolt2_Chart_Period","1"]
["ZevaChipTemperature","30"]
["ZevaCurrent","0.0"]
["ZevaCurrent_Chart_Period","2"]
["Zeva_CurrentRaw","40,0"]
["ZevaError","0"]
["Zeva_IP_Address","192.168.1.171"]
["ZevaLastReboot","2024-03-15T20:40:30.231862+1000"]
["ZevaLastUpdate","2024-03-18T09:39:22.399389+1000"]
["Zeva_MAC","43:41:4E:42:4D:53"]
["Zeva_Message","Arduino_CAN_BMS|INFO|DHCP OK"]
["Zeva_Name","Arduino_CAN_BMS"]
["ZevaSOC_Chart_Period","2"]
["ZevaStatus","2"]
["Zeva_Status","DHCP OK"]
["Zeva_StatusRaw","30,0,2,4000,547,32"]
["ZevaTemp_Chart_Period","1"]
["ZevaTemperature","32"]
["ZevaTempMax","32.0"]
["ZevaTempMin","29.0"]
["ZevaVolt","54.7"]
["ZevaVoltCellMax1","3.431"]
["ZevaVoltCellMax2","3.431"]
["ZevaVoltCellMin1","3.411"]
["ZevaVoltCellMin2","3.412"]
["ZevaVoltCellSum1","27.379"]
["ZevaVoltCellSum2","27.368"]
["ZevaVolt_Chart_Period","2"]
["ZevaVoltMax","54.7"]
["ZevaVoltMid_Chart_Period","1"]
["ZevaVoltMidDelta","0.011"]
["ZevaVoltMin","52.2"]

I am looking for input on what has proven to some as best approach for item naming. I am looking for a naming convention that is very practical and easy on the eye.
Yes, I can check the Internet, but am after the openHAB context.

E.g.,

start a group item with ‘g’ → gShed_Windows
Use of underscores (or other separator) to allow for easy split() → gDinRailRelay_02
or easy search in the GUI

Is all lowercase and word-separated with _ or -? I use underscores, because the complete word highlights when double-clicking, e.g. when marking for a copy.
Is all CamelCase? If so, is the first char lower or upper case?

What is the preference for naming say lights; or any multiple device (temperature sensor, CO2 sensor, light, etc.?
Light_01 … Light_99 or Light_Bath or Light01_Zone2
For the purpose of rules, the ZoneX should be a group?! And then work with ‘member of’?!

Any other ‘argument’? Ideas?

Any input appreciated.

Spaceman_Spiff · March 18, 2024, 6:19am

I’ve been happy the most with LOCATION-OR-TYPE_DEVICE_SENSOR where location is flexible.
E.g. Office_Window_Movement or Office_Window_Battery for a battery powered movement sensor. location. My goal is to keep the suffices consistent so I can dynamically get items without the need for groups.
With the prefix I’m flexible e.g. Weather_Day0_Rain, Mobile_User1_Alarm or PV_Inverter_Power.
Sometimes I also use multiple underscores for DEVICE, e.g. LivingRoom_Led_Lamp_1_W_Brightness which is a little bit inconsistent I guess but I was not happy with CamelCase LedLamp1.

In the end it doesn’t matter as long as it’s consistent.
With HABApp I often pass in a base name and build the suffix dynamically,
e.g. MyMovementRule('Office_Window') will create listeners for both Office_Window_Movement and Office_Window_Battery by appending _Movement and _Battery to the passed in item name.

Groups I always prefix with a g but I hardly need them.

rlkoshak · March 18, 2024, 2:35pm

I have the following simple rules:

Never refer to the technology in the Item name. That doesn’t matter and having it there does not provide any value.
Always give the Item a name that is meaningful in the context of how you use the home. “KitchenSinkLight” is way better than “ZwaveNode12_F1278_Switch”
Keep the naming of Equipment and the Point Items within that equipment the same. For example, I have the Equipment “KitchenWaterLeakAlarm” which has three Points: “KitchenWaterLeakAlarm_WaterAlarm”, “KitchenWaterLeakAlarm_BatteryLevel” and “KitchenWaterLeakAlarm_Switch” (which turns off the alarm if it’s going off). The great thing is this happens automatically when you use “add equipment to model” to create the Items through the UI. I recommend this approach whether you are using the semantic model or not. The reason for doing this is it makes it easier to define MainUI widgets that work on a whole Equipment instead of an individual Item and it makes it easier to get at the other parts of the Equipment in a rule.
Items should start with a capital letter by convention.
Try to be consistent, but don’t go overboard. Practicality is more important than anything else.

Everything else is to taste. You can make it as strictly defined or inconsistent as you want.

Particularly when you use managed configs, the names of the Items are somewhat less important than they used to be. It’s the Item’s label that is shown most prominently just about everywhere, even in Blockly rules you can toggle it to show the labels instead of names. With the Developer Sidebar you can search based on Item name, label, tags, etc and copy the name from there in those rare cases where you need it.

If you use file based configs then it’s more important to have a naming scheme that is intuitive to you beyond everything though. So no one is going to be able to tell you exactly how to do it. Just offer some suggestions.

I no longer use prefixes, the name and labels of the Item makes it pretty clear when I have a Group (though I still have some Items with prefixes hanging around I’ve not bothered recreating to rename them). In the model Locations have just the name of the location so that’s obvious. Equipment is the name of the equipment so that too is obvious. Non-semantic Groups will have a plural name and otherwise it will be obvious it’s a Group (e.g. “AllLights”, “MinBatteryLevel” (a Group with an aggregation function), etc).

Here’s a bunch of my Item names and their labels.

AdGuard_Protection - AdGuard Protection Status
AlarmClock - Alarm Clock Time
AllBatteries - Minimum Battery Level
AllChristmasLights - All Christmas Lights
AllLights - All Lights
Allspeakersgroup - All Home Speakers
Allspeakersgroup_App - All Home Speakers App
Allspeakersgroup_Idling - All Home Speakers Idling
Allspeakersgroup_Image - All Home Speakers Image
Allspeakersgroup_MediaArtist - All CC Speakers Media Artist
Allspeakersgroup_MediaControl - All CC Speakers Media Control
Allspeakersgroup_MediaTitle - All CC Speakers Media Title
Allspeakersgroup_MediaType - All Home Speakers Media Type
Allspeakersgroup_Mute - All CC Speakers Mute
Allspeakersgroup_Stop - All CC Speakers Stop
Allspeakersgroup_Volume - All CC Speakers Volume
Backdoor - Back Door
BackdoorDeadbold_AlarmRaw - Back Door Alarm Raw
BackdoorDeadbold_BatteryLevel - Back Door Battery Level
BackdoorDeadbold_DoorLock - Back Door Lock
Backdoor_Sensor - Back Door Status
Basement - Basement
BasementAirthingsWavePlus - Basement Airthings Wave Plus
BasementAirthingsWavePlus_BarometricPressure - Basement Barometric Pressure
BasementAirthingsWavePlus_Battery - Basement Airthings WavePlus Battery
BasementAirthingsWavePlus_CO2 - Basement CO2
BasementAirthingsWavePlus_Humidity - Basement Humidity
BasementAirthingsWavePlus_Illuminance - Basement Illuminance
BasementAirthingsWavePlus_LongTermRadonAverage - Basement Long Term Radon Average
BasementAirthingsWavePlus_ShortTermRadonAverage - Basement Short Term Radon Average
BasementAirthingsWavePlus_Status - Basement Airthings WavePlus Online Staus
BasementAirthingsWavePlus_Temperature - Basement Temperature
BasementAirthingsWavePlus_VolatileOrganicChemicals - Basement VOC
BasementChromecast - Basement Chromecast
BasementChromecast_App - Basement CC App
BasementChromecast_Idling - Basement CC Idling
BasementChromecast_Image - Basement CC Image
BasementChromecast_MediaArtist - Basement CC Media Artist
BasementChromecast_MediaControl - Basement CC Media Control
BasementChromecast_MediaTitle - Basement CC Media Title
BasementChromecast_MediaType - Basement CC Media Type
BasementChromecast_Mute - Basement CC Mute
BasementChromecast_Stop - Basement CC Stop
BasementChromecast_Volume - Basement CC Volume
BasementHomeMini - Basement Home Mini speaker
BasementHomeMini_Idling - Basement Home Mini Idling
BasementHomeMini_MediaArtist - Basement Home Mini Media Artist
BasementHomeMini_MediaControl - Basement Home Mini Media Control
BasementHomeMini_MediaTitle - Basement Home Mini Media Title
BasementHomeMini_Mute - Basement Home Mini Mute
BasementHomeMini_Stop - Basement Home Mini Stop
BasementHomeMini_Volume - Basement Home Mini Volume
BasementWaterLeakAlarm - Basement Water Leak Alarm
BasementWaterLeakAlarm_BatteryLevel - Basement Water Leak Alarm Battery Level
BasementWaterLeakAlarm_Switch - Basement Water Leak Alarm Switch
BasementWaterLeakAlarm_WaterAlarm - Basement Water Leak Alarm
Basement_Bedroom - Basement Bedroom
Basementspeaker_App - Basement Home Mini App
Basementspeaker_Image - Basement Home Mini Image
Basementspeaker_MediaType - Basement Home Mini Media Type
CCMainFloorGroup - Chromecast Main Floor Group
CCMainFloorGroup_Idling - Idling
CCMainFloorGroup_MediaArtist - Chromecast Main Floor Group Media Artist
CCMainFloorGroup_MediaControl - Chromecast Main Floor Group Media Control
CCMainFloorGroup_MediaTitle - Chromecast Main Floor Group Media Title
CCMainFloorGroup_Mute - Chromecast Main Floor Group Mute
CCMainFloorGroup_Stop - Chromecast Main Floor Group Stop
CCMainFloorGroup_Volume - Chromecast Main Floor Group Volume
Cerberossensorreporter_Onlinestatus - cerberos sensor_reporter Online status
Christmas - Christmas
Chromecast_Idle - Chromecasts Idle Status
Chromecast_Media - Chromecast Media
DadsOH_Heartbeat - Dad's OH Heartbeat
DadsSensors - Dad's Sensors
DadsSensors_Status - Dad's Sensors Status
Dads_House - Dad's House
Dads_Livingroom - Dad's Livingroom
Dads_Motion_Alert - Dad's No Motion Alerting
Dads_Motion_Timeout - Dad's No motion alert time
Dads_Office - Dad's Office
DadsopenHABInstanceMQTT_OnlineStatus - Dad's MQTT Status
Debounce - Debounce Items
Default_Afternoon - Default Afternoon
Default_Bed - Default Bed
Default_Day - Default Day
Default_Evening - Default Evening
Default_Night - Default Night
Den - Den
DeviceStatuses - Home Automation Device Status
DoorsStatus - Door's Status
EB_Command - MQTT Event Bus Command
EB_UPDATE - MQTT Event Bus Updates
FamilyRoomOutlet - Family Room Lamp 1
FamilyRoomWaveplus - Family Room Wave plus
FamilyRoomWaveplus_BarometricPressure - Family Room Barometric Pressure
FamilyRoomWaveplus_Battery - Family Room Airthings Wave Plus Battery
FamilyRoomWaveplus_CO2 - Family Room CO2
FamilyRoomWaveplus_Humidity - Family Room Humidity
FamilyRoomWaveplus_Illuminance - Illuminance
FamilyRoomWaveplus_LongTermRadonAverage - Family Room Long Term Radon Average
FamilyRoomWaveplus_ShortTermRadonAverage - Family Room Short Term Radon Average
FamilyRoomWaveplus_Status - Family Room Airthings Wave Plus Online Status
FamilyRoomWaveplus_Temperature - Family Room Temperature
FamilyRoomWaveplus_VolatileOrganicChemicals - Family Room VOC
FamilyRoom_Lamps - Family Room Lights
FamilyRoomspeaker - Family Room speaker
FamilyRoomspeaker_App - Family Room Speaker App
FamilyRoomspeaker_Idling - Family Room Speaker Idling
FamilyRoomspeaker_Image - Family Room Speaker Image
FamilyRoomspeaker_MediaArtist - Family Room Speaker Media Artist
FamilyRoomspeaker_MediaControl - Family Room Speaker Media Control
FamilyRoomspeaker_MediaTitle - Family Room Speaker Media Title
FamilyRoomspeaker_MediaType - Family Room Speaker Media Type
FamilyRoomspeaker_Mute - Family Room Speaker Mute
FamilyRoomspeaker_Stop - Family Room Speaker Stop
FamilyRoomspeaker_Volume - Family Room Speaker Volume
Family_Room - Family Room
FooTest - Test
FrontDoorDeadbolt - Front Door
FrontDoorDeadbolt_AlarmRaw - Front Door Alarm
FrontDoorDeadbolt_BatteryLevel - Front Door Battery Level
FrontDoorDeadbolt_DoorLock - Front Door Lock
FrontDoor_Lastchange - Front Door Last Change
FrontDoor_Sensor - Front Door Sensor
FrontPorchLight - Front Porch Light Switch
FrontRoomOutlet - Front Room Lamp
Front_Room - Front Room
Frontdoor_Raw - Front Door Raw
FrontroomLamp_Equipment - Front Room Lamp
Garage - Garage
GarageCamera - Garage Camera
GarageCamera_Raw - Garage Camera Raw Thing Status
GarageCamera_Status - Garage Camera Status
GarageWyzeCamera_HLSURL - HLS URL
GarageWyzeCamera_ImageURL - Garage Image URL
Garagedoor_Raw - Garage Door Raw
Garagedoor_Sensor - Garage Door
Ground_Floor - Ground Floor
Holiday_Afternoon - Holiday Afternoon
Holiday_Bed - Holiday Bed
Holiday_Day - Holiday Day
Holiday_Evening - Holiday Evening
Holiday_Night - Holiday Night
HomeEnergyMeter - Home Energy Meter
HomeEnergyMeter_Access - Electricity Access Fee
HomeEnergyMeter_CurrentBillEstimate - Electricity Current Month's Bill Estimate
HomeEnergyMeter_ElectricmeterkWh - Electric meter (kWh)
...

(the list was generated using the following JS code)

console.info(items.getItems()
                   .map( i => i.name + ' - ' + i.label)
                   .sort()
                   .join('\n'));

Edit: it occurred to me if I map before sort I don’t need to provide the sorting function.

You can see the Item names are not super consistent and there are several violations of my own rules, but both the Item names and labels are meaningful and that’s the most important. Even my SO and kid would be able to figure out what a given Item represents based on the name and/or label.

rpwong · March 18, 2024, 5:23pm

Also, if you change to a different device (e.g. replace a WiFi light switch with a Z-Wave light switch), you don’t have to replace the item. You just have to update the channel links.

dniklas1 · March 18, 2024, 7:19pm

I like the rules of Rich Koshak and i try to do the same.

In difference to the item names i’m using a prefix for the names of the things!
E.g “knx” or “zigbee”.

Daniel