Device options

[pvizeli]

Context

The circle with options is not closed today. We have System options, integration options but no device options. Device options are a bit different from the other options. Some device options also want to be used on UI, others only on the device page.

Today, there is a big gap between the ways how device options are exposed to an integration. Some use entity and others use service. If you are using an entity, based on the number of options, it ends up with tons of entities getting a mess on the auto UI. It isn't nice for the representation and user experience for new and exists users.

Proposal

We create a new entity device class option for:

• switch
• number

We can filter such entities on the device info page and group them differently from the real data endpoints. Future, we also need a new integration select to allow value selection, which is also common for options.

Consequences

All integration uses this device class to expose his options to his users.

[emontnemery]

@pvizeli Can you explain a bit more what you want to do, do you mean we should encourage exposing device options as entities but add the option and use that for filtering?

I started a bit on another route where device options would be exposed through a WS API, first step here to only display decice related information or status: home-assistant/core#44055

[dmulcahey]

How would things like a code for a keypad be handled? Or lock codes? Etc. There are so many variations to this that I think a WS API makes more sense and integrations can choose to implement it. EDIT: would we have to implement some way to access these from automations, scripts, blueprints etc.?

EDIT: although, I can see entities being much easier to use for users in conditions, scripts etc. Are there any concerns in bloating the number of entities with entities that rarely change? would we now have entities that cover all of the helper types?

[tetienne]

From end users perspective, it seems indeed any easy way.

But for the dev, how easily test if an option is enabled?

[pvizeli]

Using entities was a long internal discussion, but let first look at what is around. The goal is to streamline device configuration/options. Currently, if you use 3-4 integration, you have 3-4 different ways to do that, which is quite ugly and bad for user exp:

1. Use their own panel / API
2. Services
3. Entities
4. External
5. Integration configuration
6. Mixup of 1-5
7. Nothing

The solution could be:

• Generic API / Panel (could be in device info)
• Entities which using device class option

Of curse, some integration has its own Panel for a reason; I don't attack this with my description.

I personally was a long-time fan of "Generic API, But Franck and Paulus are high fans of using that as a device class. That has the benefit, it's easy to use for devs, and users can use it with a different approach and inside scripts/automation without we need to build something completely new. I agree that HA works with the entity and device class, and with System Options and Integration Options, we have 2 completely different Option systems, which his own backend, which is IMHO fine for me and makes sense. The question is, do we really need a 3 different options system or that solved with the entities, like a lot of integration using it now... Of curse, we need some kinds of "Number" Integration like selection.

EDIT:
I.e.

Someone will use the "night" option on Sonos the whole day, so he only wants once set this in the device info page. Someone other will make an automation to turn that on/off.

Of curse, with generic API, we can make also device_options service to call that. But it's still a switch. Do we need something new or do we reuse existing logic for it?

EDIT2:
We already going this route with IRSS and Battery, implemented as a device class, and that works very well. Maybe also in the future with health.

[jesserockz]

I propose that select also be considered to be an option.

[frenck]

Any entity for that matter IMHO (although it is less fitting for e.g., sensor, but that would be the exception I guess)

[jjlawren]

although it is less fitting for e.g., sensor

I can imagine some read-only data that would feel most at home at the device level. For example, a Sonos speaker can report if its microphone is enabled but it cannot be controlled remotely. I'm sure there are other sensor or binary_sensor examples that could make sense.

[Jc2k]

This would work really well for some homekit_controller devices which have settings like elevation or sensitivity that are trivial to expose as entities. And because the HomeKit API doesn't differentiate between settings and state, it also naturally handles the case for us where the setting is changed "on device" or through the official app, live updating just works on the HA side. So very much 👍

I guess my only query is if we want to use a device class or mark them some other way. Is there value in being able to know that a number is both an elevation or temperature AND a setting? Is it a state_class (STATE_CLASS_OPTION) rather than a device_class maybe?

[thecode]

I think a device class is not a good fit, since you may still want to use a different device class for some entities.
IMO this should be a new option such as category or type (or the same with prefixed with device), this will also make it possible to expand this in the future - right now the discussion is about adding something to mark an entity as device option, next week we discuss about making an entity as device management entity or something to mark entities which fit to a certain HA page (similar to area but not the same).

Another thing should be considered in this discussion (which again fit the suggestion above) is an option to mark an entity which fits all devices from the same integration or a certain group of devices. This may prevent duplicating entities if one entity has a common settings to all integration devices.

[jjlawren]

Another thing should be considered in this discussion is an option to mark an entity which fits all devices from the same integration or a certain group of devices. This may prevent duplicating entities if one entity has a common settings to all integration devices.

Does the current device registry model allow an entity to have connections to multiple devices?

[Kane610]

Not right now no

[teharris1]

Does this discussion overlap with the architecture "issue" here: #381

[teharris1]

Also feels like it overlaps with #533

[Jc2k]

If i understood this ticket correctly, I don't think there is much overlap, or at least I don't think either issue influences the outcome of this discussion.

I think #533 is about config you might have in your home assistant instance, like how you can define min and max levels for a plant sensor (in configuration.yaml). Indeed, the ticket says:

"and can not be retrieved from the "physical" entity itself".

This ticket is about a different kind of configuration, configuration that is on the physical device and can be retrieved from the physical device. E.g. if your motion sensor has a sensitivity level, thats not a setting that lives in home assistant, its a setting that lives actually on the device. The proposal is that we can model that as a number entity and let home assistant control that setting via the existing entity machinery. It is "configuration", but its configuration of the device, not home assistant.

The same criteria applies to #381. Looking at the example configuration settings you describe in that ticket, are they something that could be reasonably modelled as an entity? And is that configuration stored within the Zigbee/Z-Wave network on a physical device or is it stored by Home Assistant? If most of them satisfisy these contstraints, then implementing this will largely fix #381 as well. If not, it is a seperate problem (AIUI).

[balloob]

This has been partially implemented by introducing a new entity property entity_category in home-assistant/core#57528. The value can either be diagnostic or config. If no value is given it's state.

With this construct users can automate their config, track history for it etc. Entity categories diagnostic and config will not be part of auto-generated Lovelace, default Google/Alexa (todo)/Homekit (todo), and be excluded when targeting an area. They will be shown as their own cards on the device info page.