Teach Device Registry about primary and secondary config entries

[balloob]

Context

When we added the device registry, we added the notion that a device can be linked to multiple entities, and that those entities don't need to be all of the same config entry.

Image from device registry docs

The reason why a device can be linked to multiple config entries is because we have integrations that:

• provide extra information. If a device is connected to the network, device tracker integrations like Fritz or Unifi can provide entities if the device is connected, it's link quality (if Wi-Fi) and data throughput.
• provide derivative entities. Integrations like switch_as_x, derivative or utility_meter consume entities from a device to create new ones. Those entities will be linked to the device.

We store all config entries in a set, so we do not know which config entry is the primary responsible for this entity.

Proposal

This proposal aims to change this and allow a device entry to know which config entry is responsible.

To identify if an integration is primary or not, we can use the device info. I've identified 3 types of device info that we receive. I've opened home-assistant/core#95641 to enforce those 3 types and only needed to fix 6 integrations that were using the wrong keys. The 3 types are:

• primary: device info provides things like name, manufacturer, configuration_url
• secondary: device info provides connections (not identifiers), and the default_X properties. (note: the default_X properties exist to set the value if no value exists)
• link: this is a minimal device info meant to link to an existing entry. It contains identifiers and/or connections

Once we can identify the 3 types, we can automatically organize primary and secondary config entries:

• If a primary type comes in, the config entry is set as primary. Removed from secondary if it exists there.
• If a secondary type comes in, the config entry is set as secondary. Removed from primary if it exists there.
• If a link type comes in, the config entry is set as primary if the device entry is being created or has no primary config entry, otherwise secondary.

This logic can either live in entity_platform.py which currently forwards device info from the entity to the device registry. We could either introduce 3 new methods: async_get_or_create_primary, async_get_or_create_secondary, async_get_or_create_link. It is also possible to move all processing from entity platform to device registry and put the new logic there. Not 100% sure what I prefer.

Consequences

This allows us to:

• Improve the UI by showing the right integration icon
• Automatically clean up: we can remove all secondary entities and config entries that only provide entities for that device that is to be removed

[allenporter]

Right now DeviceInfo is a bag of 15-20 k/v pairs and it is hard to see which fields should be set or not (i introduced one of the misuses) though it didn't seem super widespread. Would it make sense to make this more explicit and have separate DeviceInfo types? If it stays implicit without introducing new types, then perhaps this is just about documentation organization into the 3 types.

[balloob]

The problem with introducing actual data classes as types is that it’s a major breaking change. We could go for a soft-approach and introduce 3 new TypedDict classes, but we would still need to parse the dict and find it’s type based on used keys (which is what home-assistant/core#95641 does).

Btw, I only found 6 integrations using an unexpected key, and it was all easily switched over. I was surprised it was so little.

[steverep]

Improve the UI by showing the right integration icon

@balloob correct me if I'm misunderstanding, but this would only guarantee that the "primary" integration icon is shown if it exists in the set, and it doesn't necessarily have to depending on the config. Moreover, I don't think the primary integration icon is always the "right" one.

I think the icon issue is one of cognitive UX/a11y, and I did my best to voice this when they were introduced in home-assistant/frontend#14184. My point there was that users will expect the icon next to the device name in a device table to identify the device in some way, not the integration. The multiple duplicate issues filed by users all verify that expectation.

For example, I have a Honeywell thermostat connected via Homekit controller and Zooz switches connected via ZWave. Under this proposal, I think I would still see Homekit and ZWave icons, but the user expectation from a cognitive perspective is to see Honeywell and Zooz icons (or something else like a thumbnail of the device).

[balloob]

You're right, in those cases we need a follow-up proposal for those integrations to be able to map manufacturers to domains to show the correct logo.

[steverep]

You're right, in those cases we need a follow-up proposal for those integrations to be able to map manufacturers to domains to show the correct logo.

Under this proposal, we would know the primary integration, which presumably identifies the manufacturer. It would then be simple to show the manufacturer logo if it exists and fallback to the integration otherwise without any extra magic. No?

I guess as a follow up unrelated to icons, what would happen if I integrate my Honeywell thermostat both with Homekit controller and the Honeywell integration? Multiple primaries? First one wins?

[balloob]

Yeah, first one wins. If there are 2 primary, and a user sets up both 🤷. I guess with Matter this might end up happening more. In that case, we could tag Matter to not have priority (assuming the native API has more features).

[steverep]

At least in terms of a frontend icon, as long as each primary provides the same device model and manufacturer (which theoretically should be the case), it shouldn't matter. Figured I'd ask in case it might lead to other unintended consequences.

[dougiteixeira]

I created the PR home-assistant/developers.home-assistant#1858 including in the developer documentation what was implemented in home-assistant/core#95641.

[dougiteixeira]

Hey @balloob, how is the category expected for tracker devices that use ScannerEntity, link or secondary?

I think it must be a link due to the implementations of home-assistant/core#63328, as it would only be created if there is another device with the same MAC address. An example is the Unifi Network integration that still has the frontend display problem due to the current category being primary.

I think that after this definition here, it would be good to include the information in the developer documentation for the device tacker entity.

[frenck]

We try to avoid device trackers being creat to prevent them from creating a ton of orphan devices.

[dougiteixeira]

That's clear, the implementation of home-assistant/core#63328 works well to prevent this.

The question is for the integrations that implement the device tracker for devices that already exist in the device registry, for example Unifi Network that currently implements DeviceInfo with the primary integration keys and causes the frontend to show the icon/logo incorrectly.

In these existing cases, is it correct to implement DeviceInfo with the secondary or link keys?

[mpoettgen]

Not sure, if that would be appropriate, but wouldn't it be relatively easy enable users to select the "primary integration" manually? For me it would be sufficient to have an option on the Device Info Card to be able to select the primary integration for the device from the list of integrations that are already displayed. This could also be an option, when a more elaborate solution fails due to some edge case.

[mib1185]

Am i wrong, or is this already full filled since 2023.8 (which includes home-assistant/core#95641)? 🤔

[andrew-codechimp]

This doesn't seem to be reflected in the UI as far as which is the primary integration and which icon to show, I'm not sure if that requires a UI change to use this.
Unifi, PowerCalc and my own Battery Notes integration all surface random icon's rather than the primary. I have adopted the device Link categorisation for adding Battery Notes devices but not seen any change in which icon is displayed.