adaptive-lighting/docs/services.md

icon
lucide/zap

Services

Adaptive Lighting provides four services for programmatic control, allowing you to integrate with automations and scripts.

adaptive_lighting.apply

Applies the current Adaptive Lighting settings to lights on demand. Useful for forcing an immediate update or applying settings to lights that aren't in the regular adaptation cycle. Provide a switch in entity_id, a list of lights, or both.

Parameters

Service data attribute	Description	Required	Type
entity_id	The entity_id of the switch with the settings to apply. 📝	❌	list of entity_ids
lights	A light (or list of lights) to apply the settings to. 💡	❌	list of entity_ids
transition	Duration of transition when lights change, in seconds. 🕑	❌	float 0-6553
adapt_brightness	Whether to adapt the brightness of the light. 🌞	❌	bool
adapt_color	Whether to adapt the color on supporting lights. 🌈	❌	bool
prefer_rgb_color	Whether to prefer RGB color adjustment over light color temperature when possible. 🌈	❌	bool
turn_on_lights	Whether to turn on lights that are currently off. 🔆	❌	bool

Example Usage

# Apply current settings to specific lights
service: adaptive_lighting.apply
data:
  entity_id: switch.adaptive_lighting_living_room
  lights:
    - light.floor_lamp
    - light.desk_lamp
  turn_on_lights: false

# Force apply with custom transition
service: adaptive_lighting.apply
data:
  entity_id: switch.adaptive_lighting_bedroom
  transition: 5
  adapt_brightness: true
  adapt_color: true

---

adaptive_lighting.get_commands

Returns the light.turn_on calls Adaptive Lighting would make to adapt lights, without making them: for now, or for a given time of day (today). Provide a switch in entity_id, a list of lights, or both.

Parameters

Service data attribute	Description	Required	Type
entity_id	The entity_id of the switch whose settings to use. 📝	❌	list of entity_ids
lights	Lights or light groups in the switch's lights to get the commands for. 💡	❌	list of entity_ids
time	Time of day (HH:MM:SS) to get the commands for, instead of now. 🕰️	❌	str (HH:MM[:SS])
transition	Duration of transition when lights change, in seconds (default: the switch's initial_transition). 🕑	❌	float 0-6553
adapt_brightness	Whether to adapt the brightness of the light (default: the switch's Adapt Brightness switch). 🌞	❌	bool
adapt_color	Whether to adapt the color on supporting lights (default: the switch's Adapt Color switch). 🌈	❌	bool
prefer_rgb_color	Whether to prefer RGB color adjustment over light color temperature when possible (default: the switch's setting). 🌈	❌	bool

Call it with a response_variable. For each light, the response lists the calls in order, each with its service_data and the delay in seconds before it (only nonzero between split calls, see separate_turn_on_commands). Only the lights and light groups in a switch's lights can be passed; without entity_id, each uses the switch it's in (of several, the one that's on). A light group is replaced by its members if the switch expands light groups. Options you leave out follow the switch, with its initial_transition, and in sleep mode the calls are for the sleep settings, whatever the time. Manual control and whether the lights are on don't change the calls. In YAML files, quote the time ("22:00:00"), since 22:00:00 is read as a number.

Making the calls is a manual change for Adaptive Lighting: with take_over_control, it stops adapting those lights until manual control is reset. A light that's off is adapted to the current settings as it turns on (unless take_over_control and adapt_only_on_bare_turn_on are enabled), so this example only changes lights that are on:

# Set the lights to the settings for 22:00, e.g., from a button
sequence:
  - action: adaptive_lighting.get_commands
    data:
      entity_id: switch.adaptive_lighting_living_room
      time: "22:00:00"
    response_variable: commands
  - repeat:
      for_each: "{{ commands.items() | list }}"
      sequence:
        - variables:
            light: "{{ repeat.item[0] }}"
            calls: "{{ repeat.item[1] }}"
        # Only lights that are on, see above
        - if: "{{ is_state(light, 'on') }}"
          then:
            - repeat:
                for_each: "{{ calls }}"
                sequence:
                  - delay: "{{ repeat.item.delay }}"
                  - action: light.turn_on
                    data: "{{ repeat.item.service_data }}"

---

adaptive_lighting.set_manual_control

Marks or unmarks a light as "manually controlled". When a light is marked as manually controlled, Adaptive Lighting will not adjust it until the manual control flag is cleared. Provide a switch in entity_id, a list of lights, or both.

Parameters

Service data attribute	Description	Required	Type
entity_id	The entity_id of the switch in which to (un)mark the light as being manually controlled. 📝	❌	list of entity_ids
lights	entity_id(s) of lights, if not specified, all lights in the switch are selected. 💡	❌	list of entity_ids
manual_control	Whether to add ("true") or remove ("false") all adapted attributes of the light from the "manual_control" list, or the name of an attribute for selective addition. 🔒	❌	bool or one of ['brightness', 'color']

Example Usage

# Remove manual control from a light (resume adaptation)
service: adaptive_lighting.set_manual_control
data:
  entity_id: switch.adaptive_lighting_living_room
  lights:
    - light.floor_lamp
  manual_control: false

# Mark a light as manually controlled (pause adaptation)
service: adaptive_lighting.set_manual_control
data:
  entity_id: switch.adaptive_lighting_living_room
  lights:
    - light.floor_lamp
  manual_control: true

# Only pause brightness adaptation, continue color adaptation
service: adaptive_lighting.set_manual_control
data:
  entity_id: switch.adaptive_lighting_living_room
  lights:
    - light.floor_lamp
  manual_control: brightness

---

adaptive_lighting.change_switch_settings

adaptive_lighting.change_switch_settings (new in 1.7.0) Change any of the above configuration options of Adaptive Lighting (such as sunrise_time or prefer_rgb_color) with a service call directly from your script/automation.

Warning

These settings will not be written to your config and will be reset on restart of Home Assistant! You can see the current settings in the switch.adaptive_lighting_XXX attributes if include_config_in_attributes is enabled.

Service data attribute	Required	Description
use_defaults	❌	(default: current for current settings) Choose from factory, configuration, or current to reset variables not being set with this service call. current leaves them as they are, configuration resets to initial startup values, factory resets to default values listed in the documentation.
all other keys (except the ones in the table below ⚠️)	❌	See the table below for disallowed keys.

The following keys are disallowed:

DISALLOWED service data	Description
entity_id	You cannot change the switch's entity_id, as it has already been registered.
lights	You may call adaptive_lighting.apply with your lights or create a new config instead.
name	You can rename your switch's display name in Home Assistant's UI.
interval	The interval is used only once when the config loads. A config change and restart are required.

Example Usage

# Temporarily change color temperature range
service: adaptive_lighting.change_switch_settings
data:
  entity_id: switch.adaptive_lighting_living_room
  min_color_temp: 2500
  max_color_temp: 4000

# Override sunrise time for the day
service: adaptive_lighting.change_switch_settings
data:
  entity_id: switch.adaptive_lighting_bedroom
  sunrise_time: "07:00:00"
  use_defaults: current

# Reset to configuration defaults
service: adaptive_lighting.change_switch_settings
data:
  entity_id: switch.adaptive_lighting_living_room
  use_defaults: configuration

---

Events

Adaptive Lighting also fires events that you can use in automations.

adaptive_lighting.manual_control

Fired when a light is marked as "manually controlled" due to a detected manual change.

Event Data:

Attribute	Description
entity_id	The light that was marked as manually controlled
switch	The Adaptive Lighting switch entity

Example Automation

automation:
  - alias: "Log manual control events"
    trigger:
      platform: event
      event_type: adaptive_lighting.manual_control
    action:
      - service: notify.mobile_app
        data:
          title: "Adaptive Lighting"
          message: "{{ trigger.event.data.entity_id }} was manually controlled"

See Automation Examples for more use cases.