Multiple ways to support a single device

[Jc2k]

This is a write up based on a conversation between devs working on HA bluetooth. In particular, the idea i'm presenting here is largely just copy/pasting @balloob.

See home-assistant/core#77284 for more context.

Sometimes we end up with multiple ways to support the same device. A recent example of this is AirThings, where we currently support cloud access but recently work was done to enable local access to these devices over Bluetooth. Accepting the new integration into core would be great but it is challenging because currently HA has a rule of 1 integration per brand. Having multiple integrations here gives the users a choice and then punts it to them completely, and gives them no help to make a choice. It is a bad user experience.

To accept Airthings BLE as our policies stand, we would have to ask the PR author to instead merge the code into the main Airthings integration. These integrations may share no code, and some of us have concerns about violating normal HA design principles like seperation of concerns as well as this exposing edge cases in other tooling, processes, etc (e.g. iot_class would no longer be a single value). As things stand thats the best approach we have so that they share a single brand, and so they offer the user a more informed choice during a config flow.

Another option could be extra metadata in the manifest.json to allow HA to group integrations together itself. This would be kind of like "reverse supported_brands". We could have a "Main" integration that is used for keying the brand icon etc. And then other integrations that are alternative_to for a specific core integration. They would be presented as one on the integrations tab, on the add integration screen and also any time we render the integration name of the config entry. Any alternative_to integration is allowed to import models from the "primary" integration for the cases where some code (such as models) is shared - Awair is an example where this would be useful.

So even though there was an "airthings" and "airthings_ble" the user flows would look more like this:

CleanShot_2022-08-29_at_16.14.00.mov

We could streamline this and make Home Assistant aware of how a device was supported and what the system was capable of. For example, don't offer bluetooth integrations if there are no bluetooth adapters. Or the choice could be visible but greyed out so that the user understands they could have completely local access, but they don't currently meet the requirements.

HA could build the user experience for this choice from manifest metadata. And we could potentially do some interesting things to help guide them. For example, we could potentially show "traffic lights" or green ticks against the choices - "Local Access", "Supports Push", etc.

HomeKit controller could participate in this in the future, but it is considered out of scope for now. (In theory we can learn that it is an alternative_to dynamically any time there is a homekit discovery match leading to a config flow, and the).

[Jc2k]

Could this approach potentially retrospectively "merge" cases where the rule was violated (i.e. some or all of the Xiaomi integrations) (this would be hard currently because there are already mulitple domains in live production HA instances around the world).

[farmio]

Thinking about solar inverters there could even be a one-to-many relationship. Most solar inverters seem to have their proprietary local or cloud API. Then there is the SunSpec specifications some manufacturers support via ModbusTCP. There is a SunSpec custom component which could probably be used for multiple different inverters alike that have their own Http API integration.

Probably the same will be true for Matter soon 😀

[balloob]

This current PR is focused solely on 2 integrations implementing integration specific APIs. ModbusTCP, SunSpec, Matter are all generic APIs and as such are not covered by this proposal.

I do think that they could easily be added in a similar way, where we have an integration that says it supports Z-Wave, Zigbee and Matter and when clicking add integration, we would ask the user what kind of device it is. manifest.json {"domain": "innovelli", "standards": ["z-wave", "matter", "zigbee"]}

[balloob]

I guess group would be a better key than alternative_to. The value of group is the "main" integration whose brand icon needs to be used.

I like this idea. Not only does it make code easier, it also helps with tagging code owners, tracking issues/PRs and integration services can target only the ones that are supported. However, it's implementation is important that the user still experiences it as a single brand in the frontend.

I don't think groups should be used if it is the same API but a different version. Groups should be used when the APIs are different at it's core, ie cloud HTTP/local HTTP/BLE. For example the Hue API should not be 2 integrations as both the v1 and v2 APIs are served over local HTTP.

Example manifest for Airthings:

• airthings the original cloud based integration. Nothing in manifest.
• airthings_ble Bluetooth API. "group": "airthings" in manifest.

Core will generate a file to easily transfer groups to the frontend, like we do for config entries etc.

The impact of this is purely in the frontend/docs. The backend would keep the integrations separately.

Integration tab

Config entries belonging to different integrations in a same group will also be grouped on this page. Just like multiple entries of a single integration are grouped (ie esphome).

Integration tab -> add integration

The integration picker will show a single entry based on the logo/name of the main integration. Once selected, a dialog will be prompted to allow the user to choose.

We can, but not for MVP, introduce some smartness where we disable an option if it relies on Bluetooth and no Bluetooth adapters are available.

Experience similar to the video of Awair above.

Device info and other places where we render logo

Brand logos will be configured with a symlink to the main integration (docs). That way we can just use the normal logo/icon URL logic.

Documentation

Each integration can still have it's own documentation page as it can come with different features.

[Jc2k]

Yes, I like this a lot. What about "brand" instead of "group"?

[bdraco]

I like brand but I think it will get confused with supported_brands so I think group is a good choice so we don't overload the brand term (I'm already confused about when to use supported brands since Home Assistants branding approach doesn't always line up with the vendors)

[balloob]

I've written up my thoughts with a more extended proposal https://docs.google.com/document/d/1990CZGDDLnYPcCHVuspwwCvgOJsHXAmr-19gWWW635w/edit?usp=sharing

[allanjamesvestal]

Hi! Longtime HA user (and new Airthings device owner) here; I found this through a rabbit hole starting at the Airthings BLE pull request. I hope it's not a faux pas to 'cannonball into the pool' here with my first-ever outreach to your dev community.

My question: I see the note that "We want [users] to control their devices locally" in that proposal doc. If a 'primary' integration (the first one created for a given vendor's products) is cloud-based — but then a local option comes along — would there eventually be a world where you'd want to switch which integration had the primary role? So that after a certain HA release, new users would get steered to the local integration by default?

If so, I think at some point it'd be worth considering how to swap which integration has the "primary" label — and what an upgrade path looks like for users on the soon-to-be-relegated variant.

(This is front of mind for me after the big advancement of "repairs" in 2022.8; this seems like a prime candidate for that kind of hand-holding guidance.)

Hope that question is useful. I'm a big fan of this proposal. I think it'll help greatly if any other primarily cloud-controlled device makers expand into local control options in the future. (Looking at Nest Protect, if I'm hoping for the moon.)

[Jc2k]

I think this is definitely worth bearing in mind.

From a UX pov I don't think it matters too much which is primary. When you click on "add airthings" we could push people to BLE even if the cloud integration is "primary". All we are really using a primary for is brand metadata, I don't think it has to be the default or anything like that.

I don't think there will ever be a "primary" that is right for every user, so i think we need to be strict about only using primary as the integration that the branding is linked to. One user might chose a push based cloud option over a polling local one because it's faster. Another will choose local because their internet is flakey. Personally I'd love whatever UI we build around this to explain which choices are local/cloud, which are push/poll, maybe the maturity level of we still think the gold stars are a good idea.

Migrating between integrations is hard. I think it's an interesting topic but probably out of scope of this discussion.

[allanjamesvestal]

Great point, and mainly just something I wanted to flag for your future discussions. I do think a system where one codebase is designated "primary" over another could lead to data-modeling (or staleness) issues — but at the end of the day, that's absolutely a topic for down the road, if at all. (And I say that greedily — I want to see the Airthings BLE bit land as soon as the architecture allows!)

Thanks to the people who put in so much effort into the UX of Home Assistant. Even alongside big technical breakthroughs like the Bluetooth standardization, this user focus has been the consistent thing that keeps me excited or inspired, release after release.