Add light.adjust service call

[chishm]

I'd like to add a new service call to LightEntitys to change the state (brightness, color, effect, etc.) of lights that are already on, without turning on lights that are off. The default implementation in the LightEntity base class would be:

async def async_adjust(self, **kwargs):
    if self.is_on:
        self.turn_on(**kwargs)

This is how scripts can implement such a feature at the moment, with something like:

script:
 - condition: state
   entity_id: light.my_light
   state: 'on'
 - service: light.turn_on
   data:
     entity_id: light.my_light
     brightness_pct: 50

Benefits over the above approach

1. Light groups can be adjusted without turning on all members

For example, I could have a light group containing all the lights in my house. At night I could change the color temperature to something warm, but only for the lights that are on.

Not all "light groups" expose their individual members (e.g. Zigbee groups), so it is currently impossible to adjust only the members that are currently on.

2. More efficient implementation for some integrations

Zigbee supports addressing an entire group with one adjust message. To replicate this currently requires a message to each on light individually.

3. Simpler scripts

The above script could be simplified to:

script:
 - service: light.adjust
   data:
     entity_id: light.my_light
     brightness_pct: 50

For scripts controlling many lights, this removes the need for looping over them, as the list of lights could be supplied in the entity_id parameter.

What I would do

1. Implement the base service in LightEntity.
2. Update documentation.
3. Implement a specialisation for the deCONZ integration.
4. Help anyone who wants to implement specialisations for other integrations.

[elupus]

I feel the need is there for light groups. I miss that same ability. I'm not fully sure how many other types of integrations could benefit from it.

[shbatm]

I think this would also be good for lights that support adjusting parameters while off. I can't find the old issue at the moment, but I know I've seen requests before to be able to send color temps, brightness, etc. without turning on a light.

[frenck]

I think this would also be good for lights that support adjusting parameters while off.

I like this comment because it hits a pain point with this proposal.

So for adjusting the light that is off, that is really depended on the light that is controlled. You can't assume all light can do that (some will actually turn themselves on, even if you didn't request that, even within a single integration). So, that cannot be universally applied.

[chishm]

I deliberately avoided the "light is already off" case because I didn't have a strong opinion. I see three options for what to do when the light is off:

1. Absolutely nothing.
2. Set the default state for subsequent turn_on commands. In the base LightEntity this could override the default values from light_profiles.csv so it works when the light is turned on from Home Assistant. Integrations may also change the defaults within their platform, e.g. what LIFX does with set_state, and what @shbatm is suggesting above.
3. Do nothing unless a "save_state" parameter is true (a combination of 1 and 2).

[shbatm]

So for adjusting the light that is off, that is really depended on the light that is controlled. You can't assume all light can do that (some will actually turn themselves on, even if you didn't request that, even within a single integration). So, that cannot be universally applied.

Based on my experience and thinking through it more, I would agree with @frenck. I would say if this proposal proceeded we shouldn't open the can of worms for adjusting lights that are off by actually trying to send any commands.

I would like to see (and this should probably be a separate topic) light_profiles.csv tossed in favor of something that can be edited in the UI and updated with a service call. Light Profiles is limited in what parameters you can set, and sometimes colors/white value/brightness just don't translate quite right. Using a scene or script, templates and helpers for trying to manage default behaviors is too cumbersome.

My specific use headache is setting a bulb or lights' default "turn_on" characteristics which are used when called from Alexa, Google Home, or a toggle/button in Lovelace. Being able to update the "default" or even "on next turn_on" in Home Assistant would allow for some better/unique controls.

For example, adjusting the default brightness of a light depending on the time of day such that the same characteristics are applied whenever the next person flips the switch, hits the Lovelace button, or tells Alexa to turn it on.

Edit: thinking for actual implementation for this piece, this could be as easy as an editable/updatable "default_attributes" state attribute or similar dict in the state machine, which is used in absence of any other parameters in a "turn_on" command.

[Gaff]

@shbatm the fix only suggests the default implementation. For light entities that support adjusting while off, they could override the default implementation.

One could imagine a future default implementation where the LightEntity maintains some internal state, so if you adjust() the light while it's off and later turn it on, it will get the correct brightness. In principle there's no conflict with other "turn_on" agents (Alexa, Google, etc...). If an agent specifies a brightness then use that. If they don't specify then use the saved brightness (but in practice there's bound to be many egde-cases). Since this is quite a lot more work and I can see that it might not be something we want to implement in version 1, but the option is there.

[protyposis]

I'm also looking for a way to adjust lights while off. In addition to LIFX, it is also supported by all Ikea Tradfri lights (can be enabled in Zigbee2MQTT via color_options.execute_if_off and level_config.execute_if_off).

Use case: Ikea lights don't support parallel transitions of brightness and color (see details), which is particularly noticeable with large changes, e.g., when turning lights on. The current workaround is first transitioning the brightness, then awaiting the transition to finish, and finally transitioning the color (which looks odd, UX-wise). For turning on, it would be great if we could first set the color, then fade the brightness in. I wanted to implement this in Adaptive Lighting, but it's blocked by the lack of support in HA.

[frenck]

For example, I could have a light group containing all the lights in my house. At night I could change the color temperature to something warm, but only for the lights that are on.

Groups can be expanded to get to this.

Not all "light groups" expose their individual members (e.g. Zigbee groups), so it is currently impossible to adjust only the members that are currently on.

This is not going to solve it fully (or better said, may cause unexpected behavior), as it is not universal / behaves as expected in many cases. For example, some lights need polling to get the correct state (are read-only). Thus this would be acting on a assumed state.

IMHO, the proposal is currently too limited to solve generic in our Light entity component.

[frenck]

there's no good way to deal with non-HA-native groups.

? Your first point in your proposal is about light groups?

Dealing with non-HA groups, is not an HA concern?

[shbatm]

? Your first point in your proposal is about light groups?

I can see @chishm's point about not being able to tell if every light in the Light Group is on and if you send a turn_on command to that, it would turn on the lights in the group that are off (versus HA Groups of light domain entities which are expandable in templates). In that sense, I can see a value in a separate command or service/parameter specific to a light.group (e.g. parameter like only_if_on or service like light_group.adjust).

Not all "light groups" expose their individual members (e.g. Zigbee groups), so it is currently impossible to adjust only the members that are currently on.

I don't think you're going to fix this piece with an "adjust" command because of the way things like Zigbee/Insteon/Z-Wave communicate to groups, which FWIU is usually 1 command to the network, which members of that group all receive and act. They'll get the command and do what @frenck mentions above -- one of many things depending on their capabilities.

You would be better off targeting the individual devices' entities using a script, or adding more scenes/groups within the external protocol to control the ones that are usually on together (smaller subsets). Or some combination of the two.

[chishm]

@Frenk wrote:

? Your first point in your proposal is about light groups?

I think I was a bit sloppy with my language. I meant groups of lights, in the generic sense, not just the HA light.group platform.

Dealing with non-HA groups, is not an HA concern?

I agree, partially. Dealing with members of non-HA groups is not an HA concern, as concluded in this rejected PR. However, dealing with features of IoT platforms is an HA concern, and adjusting the brightness/colour of lights (without turning them on) is a feature of many platforms.

@shbatm wrote:

I can see @chishm's point about not being able to tell if every light in the Light Group is on and if you send a turn_on command to that, it would turn on the lights in the group that are off (versus HA Groups of light domain entities which are expandable in templates). In that sense, I can see a value in a separate command or service/parameter specific to a light.group (e.g. parameter like only_if_on or service like light_group.adjust).

I carefully considered whether adjust should only apply to (general) light groups, but concluded that it is useful for a single light too, and that would keep the interface consistent for scripts and integrations using it (maintaining the abstraction).

I like the idea of an only_if_on parameter. It would give the same result, reduce duplication of function parameters, and not require all the plumbing for a new service. I think the only downside is the clunky concept of "turn on the lights, but only if they're on", but that is easy to explain.

I don't think you're going to fix this piece with an "adjust" command because of the way things like Zigbee/Insteon/Z-Wave communicate to groups, which FWIU is usually 1 command to the network, which members of that group all receive and act. They'll get the command and do what @frenck mentions above -- one of many things depending on their capabilities.

That's a good point that both you and @frenck have raised: not knowing the entity's supported features and therefore its behaviour. This can be fixed in the same way light colour, flash, and effect; report "individual adjust" as a supported feature.

You would be better off targeting the individual devices' entities using a script, or adding more scenes/groups within the external protocol to control the ones that are usually on together (smaller subsets). Or some combination of the two.

Targeting individual entities leads to bandwidth and "popcorning" problems, where not all lights will change at the same time (or sometimes at all). Scenes will turn on bulbs that are off. And given the arrangement of bulbs I have, it's possible I'd end up with more groups than bulbs if I was trying to represent the different combinations I have them turned on.

---

With all the above considered, perhaps I can amend my proposal:

Add a new parameter to the light.turn_on service so only lights that are already on get affected. This parameter could be called only_if_on, but I'm open to suggestions of better names. This is instead of my previous proposal for a new light.adjust service.

Also add a new feature support bit for lights: SUPPORT_INDIVIDUAL_ADJUST (again the name is up for debate). This indicates that a light entity could contain multiple physical lights, and that one command can be used (with only_if_on == True) to adjust only the physical lights that are on. If this feature is not supported then only_if_on applies to the group as a whole, and all lights in the group are turned on if any light within the group is on.

[Gaff]

For example, I could have a light group containing all the lights in my house. At night I could change the color temperature to something warm, but only for the lights that are on.

Groups can be expanded to get to this.

@frenck - can you expand on this please? I had a look at the code for light groups and it seems wonderfully simple. Every service call referencing a light group becomes a call to the individual members. This seems to be a sensible way for light groups to work :p.

Seems like if we put some fix in the light group code to skip lights that are off it will just make things more complex? And it still doesn't give you any options for the tricky cases (adjusting brightness while off, etc).

[Gaff]

...I've created a small PR to add this feature via groups: home-assistant/core#78750 - is this the kind of thing you had in mind?

[Gaff]

Just to add weight to this issue, there's lots of people in the community looking for a fix to this, one way or another:

See:
https://community.home-assistant.io/t/control-to-adjust-the-brightness-only-of-lights-that-are-already-on/461945
https://community.home-assistant.io/t/can-i-change-color-brightness-setting-when-light-is-off/243587
https://community.home-assistant.io/t/automatisation-change-light-brightness-without-turn-on/280435
https://community.home-assistant.io/t/circadian-lighting-possible-fix-to-keep-light-groups-off/221188
Another architecture discussion: #387
https://community.home-assistant.io/t/wth-cant-light-groups-only-dim-lights-that-are-on-hue-style/467208
https://community.home-assistant.io/t/brightness-control-of-groups/467178 - not /quite/ the same, but similar
Yet another proposal: #882
...

I would perhaps debate @chishm 's point 2 in their original proposal. But even if it's just points 1 and 3, I think there's a strong case for a fix here?

[tdejneka]

The links you posted, ostensibly to provide "weight", actually serve to undermine the argument that "lots of people" want this.

• The first two links point to your own posts.
• The next two are two years old and the users were unaware it's due to a hardware limitation of the lights they own (and it was explained to them).
• The last two links are about a custom component (Circadian Lighting) and how it attempts to mitigate a known limitation.

Not exactly compelling evidence that there's a great demand for a software workaround to a hardware limitation common to most smart lights (except LIFX).

[Gaff]

Fair enough, I'll remove the duplicates. This is just what I found in a few mintues of searching - I'm sure there's more. The LIFX integration is a good spot - thanks!

Is it worth adding that Philips Hue controls work this way? (i.e. if you adjust brightness / temperature / colour of a group, it only affects lights that are already on). I'd be interested to know what other lighting systems do for sure.

[LukeDefeo]

Heads up I started a similar proposal here, Its not received the warmest of receptions so far but perhaps with some input from some more people we can come to a solution to the problem at hand

[patienttruth]

Just wanted to drop in and say that the ability to adjust ONLY the lights that are already on would be excellent. 🍻

[corgana]

+1 in strong support of this. This is the killer feature for my household to be able to switch over from Hue (which does this natively).

[alex4108]

I just came over from Google Home again and found the lack of support here. It's sad, Hue and GH do this natively.

Queueing the operation until the light turns on seems like a sane path forward to me?
If HA does the light turn on, it can apply the queued ops as part of the turn on
If HA doesn't turn the light on, rather observes, it can apply the queued ops?

[agoode]

I recently filed a bug here that touches upon this issue: home-assistant/core#118009

I would like to spend some time figuring out how to move forward, since this functionality is related to several improvements I need to make before moving away from native Lutron and native Hue controls.