Modelling devices with sub-devices

[emontnemery]

Background

It's not uncommon for a single devices to contain multiple sub devices, one example is multi-gang smart light switches, where each channel in the switch as a switch or light entity as well as sensors measuring voltage, energy consumption and so on.

We currently model such devices as a single device registry entry which has multiple entities. Examples of popular integrations which support such devices as a single device with multiple entities are:

• ESPHome
• KNX
• MQTT (For example with Zigbee 2 MQTT)
• Shelly
• Tasmota
• TP-Link Kasa Smart
• Z-Wave
• Zigbee Home Automation

There are some issues with this approach:

• There's no logical link between the light or switch entities and its corresponding sensors
• The entity's entity id will be prefixed with the device name
• The entity's friendly name attribute will be prefixed with the device name
• Many entities without a clear relation on the Dashboard & Device cards

Example of a device with 4 relays and energy consumption sensors:

Device name: Left 4CH Relay
Channel names:

1. Master bedroom
2. Outdoor lights
3. Kitchen sockets
4. Gate

Entities:

• Restart button
  • entity_id: button.left_4ch_relay_restart
  • entity name: Restart
  • friendly_name state attribute: Left 4CH Relay Restart
• Channel 1 light
  • entity_id: light.left_4ch_relay_master_bedroom
  • entity name: Master bedroom
  • friendly_name state attribute: Left 4CH Relay Master bedroom
• Channel 1 energy consumption
  • entity_id: light.left_4ch_relay_master_bedroom_energy_consumption
  • entity name: Master bedroom energy consumption
  • friendly_name state attribute: Left 4CH Relay Master bedroom energy consumption

(Channels 2..4 are omitted for brevity)

See also

The same problem as raised in this discussion was recently discussed in these rejected architecture discussions, both of which essentially suggest ways to implement proposal 2 in this discussion

• Entity naming for devices with multiple channels #957
• Allow integrations to set `has_entity_name` to False #1023

Proposal

Two very different proposals are outlined below, with known pros and cons.

Proposal 1

Model devices with multiple sub devices as a main device which contains multiple sub devices linked to the container with via_device. This model is what's documented, but few integrations implement it.

From the documentation:

A device that offers multiple endpoints, where parts of the device sense or output in different areas, should be split into separate devices and refer back to parent device with the via_device attribute. This allows the separate endpoints to be assigned to different areas in the building.

Pros:

• Matches well how the device works
• No changes are needed to entity naming rules
• Changed name of a channel / or sub device will automatically change also the friendly name without extra work
• Thanks to sub devices, there's a clear relationship because the entities
• Aligned with the documentation

Cons:

• Awkward for a sub device without sensors?
• via_device has until now been used mainly for routers and hubs, which is reflected by wording in frontend

Example of a device with 4 relays and energy consumption sensors:

Main device name: Left 4CH Relay
Sub devices names:

1. Master bedroom
2. Outdoor lights
3. Kitchen sockets
4. Gate

Entities:

• Restart button
  • Included in device: Main device
  • entity_id: button.left_4ch_relay_restart
  • entity name: Restart
  • friendly_name state attribute: Left 4CH Relay Restart
• Channel 1 light
  • Included in device: Sub device master bedroom
  • entity_id: light.master_bedroom
  • entity name: None
  • friendly_name state attribute: Master bedroom
• Channel 1 energy consumption
  • Included in device: Sub device master bedroom
  • entity_id: light.master_bedroom_energy_consumption
  • entity name: energy consumption
  • friendly_name state attribute: Master bedroom energy consumption

Proposal 2

Allow integrations to opt out of having entity id and friendly name attribute prefixed with device name

Pros:

• A potential benefit is that the number of devices is not increased

Cons:

• Complicates the entity naming rules further
• If a channel / sub device is renamed, additional logic is needed in the integration to sync entity names
• Does not reduce the number of entities shown on a Dashboard or Device cards

Example of a device with 4 relays and energy consumption sensors:

Main device name: Left 4CH Relay
Channel names:

1. Master bedroom
2. Outdoor lights
3. Kitchen sockets
4. Gate

Entities:

• Restart button
  • entity_id: button.left_4ch_relay_restart
  • entity name: Restart
  • friendly_name state attribute: Left 4CH Relay Restart
• Channel 1 light
  • entity_id: light.master_bedroom
  • entity name: Master bedroom
  • friendly_name state attribute: Master bedroom
• Channel 1 energy consumption
  • entity_id: light.master_bedroom_energy_consumption
  • entity name: Master bedroom energy consumption
  • friendly_name state attribute: Master bedroom energy consumption

[emontnemery]

Upvote this comment to vote for proposal 1

[elupus]

Any way somebody could summarize more on the cons of proposal 1? I see no actual choice here, there must be a reason why there is some reason not to choose 1. Given that its pretty much how docs already state. Or some benefits on 2.

[emontnemery]

I'm not sure why no integration (that I know of) go for this solution. One reason could be that we only recently added a "connected devices" card to the device view: home-assistant/frontend#14421
The text "Connected devices" / "Connected via" makes sense when it's a router or hub which knows about other devices, but not so much in this case.

The example in this discussion looks like this:

[joostlek]

We had this discussion multiple times, leading to the initial "channel naming" proposal and later the translation placeholders.

At the time I created a PR for creating child devices for each device of the tp link powerstrip. In a conversation on Discord this was said as not-done as currently a device should represent a single physical device (unless we are talking about a house wide system with controls per room).

This PR is fixed in 2024.2 by adding translation placeholders, but I can imagine that in the future, you want to maybe combine devices. (So what if that powerstrip is connected to lets say my receiver, and I want to turn on my receiver. Currently that would require me to turn on "plug x" on the powerstrip, but if that was a separate "device" you could've combined with the receiver, you could have turned on the receiver via the receiver device page)

[emontnemery]

Upvote this comment to vote for proposal 2

[frenck]

TL;DR: No big blocker reasoning found in historical information, Proposal 1 is accepted.

I've been digging a bit into the history of this all. As far as I am aware, we've originally set out to add area support to entities to solve this problem.

Devices that could operate in multiple areas, like a 2-channel/relay style wall-switch operating lights in different areas, would presumably be solved by allowing entities to be assigned to a different area from their parent device.

Area ID support for entities was originally added to the codebase in: home-assistant/core#42221
Unfortunately, that PR provided no context or motivation behind the reasoning to do so, so I had to dig deeper.

Interesting is PR #42348, which unsplits devices because of the above-listed addition in #42221. Unfortunately, this doesn't add more context to the story.

Searching through a stack of old meeting minutes, I've found this glimpse from a meeting in September 2020:

OZW still splits a single device into multiple to resolve an area issue. We need to support entities in area’s, before we can fix that.

This indicates OZW (being implemented at the time) had a similar issue. The interesting part is, that it clearly states a device relation to areas (assumingly wall switches as well, considering the early implementation phase of OZW). But this remains guessing, as this is all the context I could find on it.

Next, I found this little gem in our private GitHub org members channel on Discord by balloob:

Anyone want to work on adding entities to areas? Store it in the entity registry. When gathering entities in an area, prioritize entity area , then fallback to device area.

This seems to be the root of the implementation. This was picked up by Robban, who created PR #42221.

Scrolling in the chat, leads to a concept document of handling Lovelace dashboards/features different: Leveraging areas (e.g., using views or cards).

This one is surprising, as that one indicates how Shelly is one of the drivers behind the area ID to entities change (just like Shelly is a driver behind this proposal as well).

Add entities to the area registry. It is important that we can put as much in areas as possible. Internal entities have no device, so this will solve that. Also solves devices having entities in different rooms (Like a Shelly 2).

The reasoning is thus two-fold. One is device-less entities, the other is devices providing entities that could be in different areas. This changes the perspective a little. First of all:

• Almost everything has a device in Home Assistant nowadays. But in 2020, that was most definitely not the case.
• We have tons of more entities provided by a device compared to back then.

I think adding/making exceptions for entities for the areas they are in is still valuable and still holds. We can still have integrations providing just entities (most notably helpers).

We do have tons of devices providing a lot more entities. That same light switch now provides configuration entities (like power-on behavior) and diagnostic entities (like power consumption and energy usage). Assigning each and single one of them to a different area is a pain for the end user.

I haven't talked about naming yet... The recently added placeholder supports the above historical model, and IMHO still valuable (I've seen it deployed for other reasons too), so that addition was a win.

We've discussed this extensively (Paulus, Erik, Martin, Robert and me), and we agree that Proposal 1 would be the path to take unless we found good reasons in our history not to do so. Conclusion on the above:

The drive behind the history of adding areas to entity IDs is definitely related, but not exclusive to that use case alone. Things changed a lot, we have tons of entities and data points from our devices nowadays that made the original feature set out to solve this (adding areas to entities), not a full fit anymore.

Meanwhile, we have improved our UI. We have links from parent devices to their child devices on the parent device page, for example, making them easier to find and navigate around.

Let's do this.

../Frenck

[ChristophCaina]

Another example would be ecowitt weather Station.
On this, the WiFi hub will be set as device, aber so all the Sensor/entities will use the hub's Name.

But I could Connect different Stations / Sensors to one hub - Here, it would make Sense to use "subdevices" in my opinion