Separate names into `fallback_name` and `forced_name` (for DIY Zigbee devices)

[TheJulianJES]

Background

Due to custom quirks, fallback_name was introduced in quirks. It provides the default English name we use to generate strings.json for translated entity names in HA and allows users of custom quirks to name their entities, without modifying and generating Core translation files.

Home Assistant will only use this name if (1) no translation value(!) is provided and (2) if no device class (which have a name) is set.
Home Assistant does both of those actions via its internal name resolving method. However, this also means that device class names take priority over fallback names (if no translation value was found for the given key).

(Copied parts below from a related issue: zigpy/zigpy#1523)

More explanation

This is an issue in the ZHA integration in HA we can't really fix (easily). The following priority of names occurs:

1. Translation key (handled by HA)
2. Device class name (handled by HA)
3. Fallback name (handled by ZHA integration)

When a quirk is officially added, zha-quirks is bumped in the ZHA lib, and the ZHA lib bump eventually makes it way to HA.
We automatically update strings.json in HA with the new translation keys and the fallback_name for (US) English.
So, this is only really an issue with custom quirks, as translation keys/values (or the device class name) will always exist upstream.

Normally, HA fully deals with the name (as entities are generally added via HA only). ZHA is a bit special, as there a lot of devices (Tuya) and even custom devices, so it makes sense to provide some (basic) entity support/metadata from the quirks lib. But to even allow the entities to have a name during development at all, we had to introduce fallback_name and it'll only fall back to that if HA wasn't able to find a name before (translation key value or device class name).
We can't really change HA without re-implementing what HA internals normally deal with.

Our issue (most important part of this issue)

But there's one issue that not only custom quirks have, but we have as well:
AnalogInput, AnalogOutput, BinaryInput, BinaryOutput, and so on, all have a description attribute that manufacturers can use to name the resulting entity (in Home Assistant). Matter has a similar concept with its label attribute.

But we currently set the fallback_name to the value of the description attribute if it's supported and not empty. This won't force the name to display if a device class is set. With our current implementation, this likely can't happen, as we never set the device class (IIRC) for these kinds of entities, but:

We should still provide a separate "forced_name" (or just "name") attribute in the BaseEntityInfo that will take priority over translation key, device class name, and fallback name.

ESPHome / DIY Zigbee devices

Most manufacturers don't actually use the description attribute, or just misuse these clusters in general.
However, multiple (still custom) components and ESPHome PRs exist that allow to expose custom Zigbee entities. These generally need to be named in a similar way to how is allowed by using the ESPHome integration in HA. To allow this, the description attribute is set.

We should make sure all these clusters/entities always show their name set in ESPHome. Like mentioned above, for those names, we should set a "forced name" attribute, not just fallback_name.

Future

In the future, we may wanna see if we can improve the situation with the fallback_name even further, especially regarding the situation described at the top of this issue. The code in HA for the fallback name is also a bit "hacky".

[puddly]

So the proposal you're making is, priority-wise:

1. forced_name, set from description if no translation key or device class is present. Would also be used for DIY devices with custom quirks.
2. Translation key (handled by HA)
3. Device class name (handled by HA)
4. Fallback name (handled by ZHA integration)

fallback_name will always be provided for every entity without a device class, since we generate the English translations from it. Do I have it right?

---

For description especially, this brings up a conflicting layering of naming priority:

Devices can self-name entities with description but we ideally want to be able to translate them with a quirk, if needed. I think this use case is handled by change_entity_metadata. (I'm looking more closely at it and I think we don't actually provide a way to set an attribute to None, we should maybe have the kwargs default to an UNDEFINED singleton or something to allow the fallback name to be unset?).

[TheJulianJES]

I think that's correct for the most part. Small details:

1. forced_name, set from description, overriding anything else: translation key AND device class (are not used).
   Mostly used for DIY devices with no custom quirks, so by the AnalogInput, AnalogOutput, BinaryInput, BinaryOutput, since we auto generate these entities in ZHA, even without a (custom) quirk.
   This will basically just set _attr_name to forced_name in HA (which is description) if it exists.
2. Translation key
3. Device class name
4. Fallback name

I think we'll need to all handle this in HA for the most part (due to the translations and device classes being in the middle priority-wise and them being HA concepts).

---

fallback_name will always be provided for every entity without a device class, since we generate the English translations from it. Do I have it right?

Yes, it always exists to force a description of the entity in quirks and to allow for other (non-HA) projects to use quirks v2 metadata to generate "entities" on their platform, since they won't be able to get the names for the (quirks) device classes, since they're only defined in HA. So, they'll likely just always use the fallback_name.

Like, all quirks v2 metadata (entities) should have some kind of name defined that makes sense, even when HA is not used. We also "want this" for the ZHA library (e.g. for diagnostics and tests).

Devices can self-name entities with description but we ideally want to be able to translate them with a quirk, if needed. I think this use case is handled by change_entity_metadata.

So, Matter also provides manufacturers and users to set a custom "label" that takes priority over anything else in HA. Seen here: https://github.com/home-assistant/core/blob/0cebca498c338ad07c3df83f1a32528c82dcadd0/homeassistant/components/matter/entity.py#L115-L134
They are not translatable at all right now.

I've not seen any manufacturers actually use the description attribute, but if there are commercially available devices that do this, we should provide a way to translate them (and would likely unset the forced_name in ZHA then).

But this should be quite easy to do as well.

I'm looking more closely at it and I think we don't actually provide a way to set an attribute to None, we should maybe have the kwargs default to an UNDEFINED singleton or something to allow the fallback name to be unset?

That's a good point. We should probably allow that in general, but we should never really unset the fallback name, per what I mentioned above.

[puddly]

I've not seen any manufacturers actually use the description attribute, but if there are commercially available devices that do this, we should provide a way to translate them (and would likely unset the forced_name in ZHA then).

Frient does this with a few of their devices.