Allow editing entity name instead of friendly name

[piitaya]

Context

It’s been more than 2 years that the entity naming as be introduced to Home Assistant. (See blog post to announce entity naming).
Almost all core integration is using the new naming conventions and entity names translations has been introduced.

However, the new naming convention is not completely used in Home Assistant. The front-end still use the old friendly_name instead of using the entity, device and area registry names.

Currently, according to the documentation, the friendly name is computed this way :

The entity is not a member of a device: friendly_name = entity.name
The entity is a member of a device and entity.name is not None: friendly_name = f"{device.name} {entity.name}"
The entity is a member of a device and entity.name is None: friendly_name = f"{device.name}"

When a user rename the entity, the friendly_name is set, not the entity.name.

This behavior has some cons :

1. This inconsistency makes it difficult to understand for the user and most users are prefixing manually the entity name with the device name to restore the original format provided by the integration (f"{device.name} {entity.name}")

2. In the front-end, there is some hacky stuff to find and replace the old device name by the new device name in the friendly_name and it can lead to un-sync names.

3. How devices and entities should be named is a frequent community discussion topic:

   • How do you name your devices in 2024?
   • Naming convention regrets?
   • How do you all name your devices?
   • etc

Proposal

The proposal is to allow user to edit the entity.name or the friendly_name. If the user choose to edit the entity.name the automatic computation of friendly name can be preserved.
In fact, renaming the full friendly name is still possible because some devices are multiple devices (shelly em or power strip) and some integrations still don't use entity naming.

It can be done by adding an option : Use entity name as friendly name or override friendly name or ignore device name. (I could figure out a good name for this settings for now but you got the idea).

Home Assistant front-end will also be updated to not use the friendly_name anymore and will do the computation depending of the context (see potential application below).

Renaming the entity.name must be the default to respect the has_entity_name rule.
The new option can be set to true during the migration if the renamed entity doesn't contains the device name to avoid name changes after update.

The friendly_name will still be exposed as an attributes because many (if not all) custom cards relies on that. Voice and native app are also using this attribute.

Potential applications

1. Use a different separator between device and entity name depending of the context ( -, :)
2. Display the name in 2 lines
   • in the entity picker
   • in the more info header
3. Omit the device name when not necessary
   • in device page : Don't show the device name (already implemented by manually striping the name in the default dashboard).
   • in cards : for a entities cards, don't repeat the device name in every row (already implemented by manually striping the name in the default dashboard).
4. Omit the entity name when not necessary
   • in cards : for a battery section, we don't need to include the entity name and we can use the device name.
   • in energy dashboard : only display the device name if the device contains only one power entity.

Concrete example

By default, the integration provides a name for the device and the entity

Initial values

Device	Entity default name	Entity user provided name	Friendly name
Power meter	Consumption 1		Power meter Consumption 1
Power meter	Consumption 2		Power meter Consumption 2

Then the user decide to rename the entities.

Current behavior

Device	Entity default name	Entity name provided by user	Friendly name
Power meter	Consumption 1	Off-peak consumption	Off-peak consumption
Power meter	Consumption 2	Peak consumption	Peak consumption

Proposal

Device	Entity default name	Entity name provided by user	Use as full name	Friendly name
Power meter	Consumption 1	Off-peak consumption	false	Power meter Off-peak consumption
Power meter	Consumption 2	Peak consumption	false	Power meter Peak consumption
Power meter	Consumption 1	Off-peak consumption	true	Off-peak consumption
Power meter	Consumption 2	Peak consumption	true	Peak consumption

For that reason, many users are prefixing the device name in every renamed entity.

Potential issue

Adding a new option can complicate the entity settings.

[DubhAd]

I understand the desire here, but this needs to be very carefully handled, and ideally needs to be discussed with the community, not simply delivered as a fait accompli as part of a Beta release. Anything else is going to result in further pissing off the end users, something the project can ill afford to do right now.

[joostlek]

But this currently is not delivered in a beta, this is a proposal that is here to gather feedback from the (dev) community. So if this is a reason it will piss of end users, I think it will be insightful to leave behind why.

From a personal note I don't see a bad thing in this necessarily, but I only have 2 rooms and 30 square meters, so I don't have a lot of naming issues others have. (And given that I also don't care that much about naming of my entities).

[parautenbach]

I read @DubhAd's point to mean that dev agreement wouldn't be sufficient to go ahead. Technical feasibility is but one aspect.

I wouldn't like a naming convention forced upon me that cannot be overridden. That's point one. The second point is, don't touch my existing device and entity names (doesn't look to be a concern here, but mentioning it nonetheless).

[joostlek]

In the end a decision will be made by developers, but they are fed with input from the community.

So hereby an invite to leave your thoughts in a separate thread, I am genuinely interested what you think about the proposal and what you like or dislike.

[hilburn]

I would really dislike this personally.
To give an active example - I have a device "Living Room TRV 1" - easy to read and understandable.
Within this there are a number of entities I leave as default naming because I only need to reference them once to live in an automation and who cares, however others (like the actual climate entity, battery soc) I actually want to display in cards and I rename to strip out the "TRV" because when it's in the context of the climate control card and dashboard, I don't want to waste screen real estate on printing out TRV 15 times
Additionally, this has the risk of being an extreme annoyance in the entity selector which is often width constrained and cuts off the friendly name, especially on phones and config flow windows, forcing device name at the start would lead to instances where multiple entities look identical, because the details of the entity are not displayed

[Madelena]

This proposal is designed to address the problems you mentioned and help you strip out the repetition in names automatically on the dashboard.

In most scenarios, the device will likely be still named as " ", i.e. Living Room TRV 1, and the entity names will also follow the format " ". And since Home Assistant now knows how the name is composed, it knows which part of the name to strip out in different circumstances. For example, on a Living Room dashboard, it will know to take out the word "Living Room" from the entity name to keep the name on the card short. In an entity selector, since it knows how the name is composed, it knows to truncate the middle of the name and leave the most important part of the entity name intact.

Additionally, users can still override the device name and entity name, or the name displayed on the card, if they want to.

[tetele]

The way it is at the moment, this proposal seems to be based on reasons which only have to do with ease/uniformity of implementation. Are there any user-facing reasons to make this change? Having these reasons included in the proposal might make it sound more useful to the masses.

That said, I think the naming pattern is a matter of personal preference and I would not dare to think that there is a majority for any option. It's a good idea to have separate strings for device name, entity name etc. and it would be lovely if users could get to pick how their entities would be displayed in general, with per-entity overrides possible.

I like the idea of having both the entity name and device name in entity selectors. Particularly if i could search by both (in the same input, of course).

Personally, I name my entities using area/device, purpose and some differentiator (if needed). E.g. "Kitchen window", "Living room couch lights", "Washing machine power consumption" etc. The power consumption is an entity of the device "Washing machine", so the naming scheme makes sense. The light pertains to the 2-gang light switch, but i'd never have it called "Living room light switch 2 Couch Lights", that'd drive me mad.

Maybe users should be allowed to define/pick a default friendly naming scheme for new devices, but also be allowed to tinker friendly names on device addition. I don't think that one scheme would cover all cases even for a single user, let alone for the entire userbase.

Regardless of the approach taken, what's important is that I (and others) have spent time on creating dashboards with entity names about which I don't have to think, I simply rely on photographic memory. Having them changed now would be a nuisance I would not want to deal with, if given the choice.

[tetele]

There are surely times when any combination of {area}, {device name} and {entity name} are not enough and when I want to have a custom friendly name. Let me get back to my previous example.

I have a few switches in my Living room area. One of them is called Living room switch 2. It controls 2 lights: Living room couch lights and Living room spots.

How would this change help me name my Living room couch light?

Here's another example: I have another switch in my Kitchen, called Kitchen switch and has the device area set to Kitchen. One of its entities is Parking light, which controls the light in my Parking area and has the area set to Parking. How would this work?

Obviously, I don't want to rename anything, as I've already spent a lot of time naming stuff.

[piitaya]

Yeah the main issue is for device that are not really a device and control multiple real device. That's why the option to rename the full name should still be an option. Or we should be able to split a device into multiple.
But for most case, user only want to rename the entity name, not the full name (device + entity).

[tetele]

Home Assistant front-end will also be updated to not use the friendly_name anymore and will do the computation depending of the context (see potential application below).

This worries me (it's from the updated proposal). I'd change the names in the frontend ONLY IF the user intervenes to make changes. Alternately, there could be a deprecation period in which users get notified (via a repair ?) that they must make changes to their frontend config so that when the change happens (after the deprecation period), they have already made a choice and what gets displayed will be predictable.

[piitaya]

Why would they need to do front end changes?
It will just be as before for dashboards (no change at all) and some place will be updated to display the device and the entity name on two lines instead of one.

[tetele]

Then i must have misunderstood what you were proposing.

[parautenbach]

For me, I need to way to completely override whatever the backend would do automatically. I'd like to retain the ability to provide a name that's used everywhere, unless overridden e.g. on a card level.

Where you maybe want a shortened name, the additional context might be provided by a heading of a section, title of a card or a device page. For example, I don't need to see "Living Room Temperature" when a card's title is "Living Room". Just showing "Temperature" then as an entity name is sufficient. This will vary on a case-by-case basis.

One must distinguish between what is a display issue from an internal name. The entity ID is what is always unique. Names don't need to be. Also, entities are often linked to devices and in such cases the UI provides a way to navigate to the device to see all related entities.

I'm struggling to see where this will be used: Only in built-in pages, like entities, settings, and such?

The proposal is to always include the device name as prefix for the friendly_name, whether the entity name is renamed or not.

I cannot agree with this. There must be a way for a user to provide a name that fully overrides any form of automatic naming.

The front-end will use the entity registry name and device name to display the name.

I'm ok with this where no name has been provided, but I think the solution needs to be refined. Simply concatening the parts isn't the best option in my view. At least include a separator (e.g. device name: entity name).

I have e.g. a bed occupancy device, call it "Bed Occupancy". It has a binary sensor, "Bed Occupied". Under this main proposal, this becomes "Bed Occupancy Bed Occupied". Doesn't look great, even though the individual names make sense.

Coming from a frontend perspective, I think it would be better to have renaming elements and a kind of templating functionality. In other words, you have a pill for "device name" and a pill for "entity name" that you can drag into a name field and order and add other text in a way you want. No need for a templating language to be exposed to a user. This makes the implementation explicit instead of implicit and noted in some documentation where many users won't read it.

The friendly name will be only used in Home Assistant front-end for backward compatibility and old entities that are not in the entity registry.

Why can the friendly name attribute not be retained as an override? Is there a technical reason for this?

[piitaya]

So basically, something like this

Device	Entity default name	Entity name provided by user	Use as full name	Friendly name
Power meter	Consumption 1	Off-peak consumption	false	Power meter Off-peak consumption
Power meter	Consumption 2	Peak consumption	false	Power meter Peak consumption
Power meter	Consumption 1	Off-peak consumption	true	Off-peak consumption
Power meter	Consumption 2	Peak consumption	true	Peak consumption

[parautenbach]

A UI option like that would be good, but I'd also like to retain an option in YAML.

[piitaya]

Yaml entities are not concerned as they are not part of a device.

[parautenbach]

I'm referring to how a friendly name can currently be set for any entity via a customize section.

[Madelena]

I agree that the ability to override device name and entity name, as well as the name of the cards on the frontend, will address the issues.

From what I understand, the current proposal will allow it. For example, if I want to call my light "Big Chandelier" instead of "Living Room Light", it should be possible, and it will rename of its entities "Big Chandelier Light", etc.

[abmantis]

we can propose a option in the entity settings (stored in the entity registry) to remove the device name from the friendly_name

Should this part be made more prominent in the proposal? That option makes this proposal something that improves on what we currently have by giving users choice between fully overriding the name vs. having the prefix.
Without that option, we would be forcing device names as a prefix even when that is not desirable.

[piitaya]

Yeah, I will edit the proposal according to it. It should be a prominent option according to the feedback received here.

[piitaya]

I edited the proposal to offer it as an option. It was at the bottom of the previous proposal, it is now included in the proposal more clearly.

[hilburn]

Will there be a global option to default that check box to false? Renaming entities is already tiresome, avoiding a new extra click would be good.

[arturpragacz]

I've had the exact same idea for 2 years already (from the very beginning as has_entity_name was introduced). It never made sense to me that you had to repeat the device name constantly when renaming entities. I even mentioned it to frenck recently.

So I obviously overwhelmingly support this proposal.

I have however some additional remarks. What I don't fully like is that I think the proposal doesn't go far enough.

There are two problems that I see.

Friendly name

Firstly, we should be completely clear that the goal here is to eventually remove friendly_name. It is a remnant of the past, that has to go. Obviously, the road to that point will take quite some time and will have to be full of long deprecations to allow for the whole Home Assistant ecosystem to transition smoothly. But we should be clear, that this is the ultimate ambition.

As was noted in OP friendly_name is currently used not only by frontend, but also by other things: voice, native apps, templates, it is present in the state machine, etc. These will all need to be handled separately, with individually crafted strategies. Voice assistant support in particular could gain a lot by this, as the current treatment of names works out of the box only for English and a few other grammatically similar languages, but breaks spectacularly for most languages of the world.

That being said, we have to start somewhere, and frontend is the obvious choice here. We can transition all the core frontend functionality and then introduce a long deprecation for the custom cards. Speaking of cards, both core and custom, they should be treated with special care here. What every card should offer is a choice to the user, what context should be shown on it. Then it can always be customized in a way that makes local sense. Cards in a dedicated area section for example could be configured to omit the area context, to make the interface look clean and nice.

We should also probably decide on some guidelines how the context should be displayed: multi-line or single-line, what separator to use, etc. We currently effectively use whitespace as a separator, which works well for English, but again not so much for many other languages.

Name context and registries

Secondly, I'm not a fan of "Use as full name" attribute. It is very clearly designed for a backwards compatibility only usage and as such is a wasted opportunity.

Instead I propose to add name_context to entity entries in the entity registry. It can contain values: "device", "area". It can also be empty.

The idea is that this is the minimal context in which entity name makes sense. Some examples:

• battery sensor, part of device "Door lock", with entity name "Battery" and context "device"
• light entity, part of device "Bedroom light" with entity name None and context "device"
• switch entity, part of device "Power strip" with entity name "Lamp", area "Living room" and context "area"
• switch entity, part of device "Power strip" with entity name "TV Power", area "Living room" and empty context
• light group entity, not part of any device, with entity name "Lights", area "Kitchen" and context "area"
• template entity, not part of any device, with entity name "Guest mode", area "Configuration" (or no area) and empty context
• media player entity, part of device "Receiver" (multi-zone avr), with entity name "Music", area "Bedroom" and context "device", "area"

This context from the registry could also be used as a default for all the cards, if there are no special considerations and it wasn't reconfigured in the card by the user.

In all the other interfaces (device page, area page, entity picker, etc.) frontend would be smart about what context to show and what to hide, just as it was described in the OP, but with the benefit of greater understanding as to in which context the entity name is valid.

For example imagine that you have the light group entity from above and you show it in the "Kitchen" area page, you can simply show it as "Lights" instead of displaying "Kitchen Lights" redundantly.

Backward compatibility

This would off course remain backward compatible - the friendly_name would simply be generated according to the following:

device_context = device.name + " " if "device" in entity.name_context else ""
area_context = area.name + " "  if "area" in entity.name_context else ""
friendly_name = f"{device_context}{area_context}{entity.name}"

As a result we would get for the examples above:

• Door lock Battery
• Bedroom light
• Living room Lamp
• TV Power
• Kitchen Lights
• Guest mode
• Receiver Bedroom Music

[Petro31]

My idea's behind this separate device and entity names.

Right now, users have a hard time understanding the naming structure with devices and names in HA. Largest points of confusion:

1. The name of the device is missing in the device page, but present in some pages of the UI and not present in others.
2. Depending on what dashboard/card you use, the device name seems to have a mind of its own unless you take over the UI and name everything manually.
3. If you rename a device and do not rename entities, users do not know how to recover without altering entity names one by one. I can’t count how many times I’ve had to explain: “change the device name back to the original device name, click no to the question and you’re back at square 1”.
4. The renaming entities (and their entity_id) system is not clear. It’s a single option and you don’t see a previewed outcome.
5. Sometimes with specific integrations (MQTT, ESPHome), it does not make sense to include the device name in the entity_id.

To solve these issues, we should completely remove the current system and replace it with something that’s more intuitive to the user. Doing string replacements inside a single field behind the scenes does not make sense to anyone outside programming.

Solution

Entity and Device Names

1. Separate Device name and Entity name in config entries (if it already isn’t).

2. Provide the ability to rename the device.

3. Provide the ability to rename the entity.

4. Add dashboard, view, section/grid/stacks, card options to include/exclude device names.
   This will be a select selector with 3 options. (Names for options are TBD):

   • Inherit - This will pull the option from the parent.
   • Include - Include the device name.
   • Exclude - Exclude the device name

   Device name inherency behavior (top to bottom):

   • Dashboard - Default selection is (Exclude)
   • View - Default is inherit from the dashboard.
   • Section - Default is inherit from the view.
   • Grid, stack cards - Default is inherit from section or view if section is not present.
   • All other cards - Default is inherit from grid/stacks or section if no stack is present. If no section is present, inherit from the view.

   When name is provided in the card configuration, the device/entity naming option does not impact the name field. The user’s input for that field is honored. I.e. The “include device name” option only impacts cards using the “default name” provided by the card itself.

5. All pages in the UI (outside user dashboards) only show the entity name. Device name is fully separated.

Default entity_id generation

1. Add an option to include device name in the entity id when creating the entity’s entity_id. This option will be housed on the 3 dots system options for the integration or in a new integration wide settings page. This could also be system wide.
2. Renaming the entity_id will be available from 3 spots.
   1. Entity configuration page (no change) - All manual. Long term could add options from below.
   2. Entity list
      1. This will be a bulk naming option. Users will enter selection mode, select any number of entities, click the 3 dot menu and select “Rename Entity_ids”.
      2. This will open a pop up with draggable options as chips:
         1. Custom Field (can type in this field/chip, if this isn’t possible add a field for this)
         2. Area
         3. Floor
         4. Device Name
         5. Entity Name
            The options can be dragged in any order.
            The options can be omitted.
            When the form is submitted, the entity_ids will be updated to the dragged order.
   3. Device page.
      1. User will click 3 dots and select "rename entity_ids"
      2. This will open the same pop up as the entity list in 2.ii.b.

[tetele]

Add dashboard, view, section/grid/stacks, card options to include/exclude device names.

I'm not sure this is completely related to this initiative, but there are cases where something other than entity name (with/without parent device name) is suitable. As an example, Say I have a section with all the window binary_sensors. I'd like all entity/tile cards in that section to reflect the entity's area rather than name.

Could this be factored into the change somehow?

[Petro31]

It's not really related, however all these things are intertwined at the moment and I wanted to document my ideas somewhere.

[tetele]

Took me nearly a day to figure out this was an old proposal, one to which I've already replied 🤦

[cadavre]

Hi @piitaya, any follow-ups on this?

Some time ago, I gave this topic some thought and shared an initial idea draft on Discord:
https://discord.com/channels/330944238910963714/1381315688274202695

I believe this topic goes well beyond just Frontend concerns. What would really be beneficial is the creation of a contract – essentially a naming specification – that all Open Home Foundation-certified members could adopt.

Area naming

At first glance, this might seem straightforward – but it's not, especially when floors come into play.

For example, consider areas like "Bathroom" that exist on multiple floors. How should this be handled?

• Do we create an area named "Bathroom" and assign it to "Ground floor", then another "Bathroom" assigned to "1st Floor"?
• Now you have two identically named areas – which one is which?
• Do we suffix them, e.g., "Bathroom 1", "Bathroom 2"?
• Or should we embed the floor name into the area name itself, like "Ground floor Bathroom"?

There’s no clear consensus here yet.

Device naming

This is probably the trickiest part without a clearly defined contract, since users will each have their own logic – and in many cases, they’ll all be right in their context.

Consider:

• Some devices are home-wide, like a main power meter.
• Others are highly repeatable, like lamp switches.

That means naming should adapt to device type or context.

It also gets more complex with:

• Area-wide devices.
• Multi-entity devices (e.g., wall switches controlling light and a fan).
• Devices that control other devices (e.g., a smart plug switching a fan on/off).

These differences suggest the need for a flexible but consistent naming convention.

Entity naming

Entity names should ideally be auto-generated from device and area names, based on the contract – but also be compatible with multiple frontend use cases.

With recent frontend changes (entity lists, displaying IDs or not, more-info modals, etc.), the old naming conventions are no longer sufficient.

---

Cases:

You have two bathrooms, in one you have a single smart heater:

[floor]Ground [area]Bathroom -> [device]Heater -> [entity]Climate

You have one bathroom with two old-fashioned heaters, controlled by one smart switch:

[floor]- [area]Bathroom -> [device]Wall switch -> [entity]Heater 1
[floor]- [area]Bathroom -> [device]Wall switch -> [entity]Heater 2

You have all areas assigned to floor, but you actually have one "Kitchen" so no need to add floor name:

[floor]- [area]Kitchen -> [device]Wall switch -> [entity]Lamp (manually renamed)

Etc.

---

@piitaya I can see that currently almost everywhere a device is described by an area name. Does HA statistics tells that most users actually create and assign areas? This is great, but areas on the other hand are something that user must do manually.

Don't you think that having an official document of recommended naming policy would be helpful for anyone looking on ideas how to name their entities? Eventually lots of people may have different ideas which not all will be supported by worked-out display policy.