Home Assistant: Naming Convention
Overview
A boring yet important topic that I’m sure many have come across in their working life. Home Assistant has it’s own naming conventions for developers. This topic falls into do what you want but I’m of the nature to try and standardise. This is a subjective topic so this is my way of doing and it’s not necessary right for you.
Why?
The naming convention I want to focus on are the entity IDs. Without looking, I would guess all my scripts and automations refer to at least one entity ID. If the IDs change, it can be quite impactful. I know because I started off wrestling with the IDs into something that makes sense to me only to find re-pairing devices becomes even more painful when they resort to the default names.
My Standard
Starting with naming the device as this can influence the way the entity IDs are generated. I generally associate the devices with a room. For example, Kitchen Door. Where is it? In the kitchen. What is it? a door (sensor). With the SmartThings contact sensor, it has a multitude of sensors built in and cascades to entities like kitchen_door_contact, kitchen_door_acceleration, kitchen_door_temperature. All of which are easily understandable, memorable and relatable.
If the device needs to be re-paired/added then the entity IDs should be the same defaults.
When are there are multiple of the same thing, I try to differentiate as much as possible. For example, I have to lights in the kitchen with their own light switches. I named one Kitchen Table and the other Kitchen Cooker.
There are exceptions of course. For example naming something would mean a really long entity ID, nothing to differentiate the objects other than there are more than one, I would append a counter to the end of the name. Using the Kitchen door example, if there were 2 doors I would name one door Kitchen door. The next one to be Kitchen door 2. The entity IDs would become kitchen_door_contact, kitchen_door_2_contact and change the friendly name to be something more meaningful. What is too long is a judgement call at this time. My own guidance is anything that will have more than 100 characters then it’s too long.
Customizations
The display names of the entities may be less user friendly. For example, Kitchen Door Contact. I would use the customization in Home Assistant to rename the name of the entity but preserving the entity ID. This way, any dashboards will use the friendly name.
Summary
The rules I have on settled on are:
- Use area and object for device names
- Try to give devices a unique names where possible
- Where you can’t append a counter at the end
- Keep to the default entity IDs
- Use friendly name customisation for better display names.
