remote/adaptive-lighting
1
0
Fork 0
mirror of https://github.com/basnijholt/adaptive-lighting.git synced 2026-10-29 06:37:13 +01:00
Code Issues Projects Releases Packages Wiki Activity
adaptive-lighting/docs/services.md
Mathias Berglund d26fadc5bb ✨ Add adaptive_lighting.get_commands service 
A service that only returns data: for each light, the `light.turn_on`
calls Adaptive Lighting would make to adapt it, now or for a given time
of day (today), without making them. Each call has its service data
and the time to wait before it (between split calls, with
`separate_turn_on_commands`).

This lets automations use Adaptive Lighting's curves for other times,
e.g. to step lights to later or earlier settings from a button: when
the automation makes the calls, Adaptive Lighting treats them like any
other change (with `take_over_control`, it stops adapting those lights
until manual control is reset).

- Only the lights and light groups in the switches' `lights` are
  allowed. Without `entity_id`, each gets the calls of the switch it's
  in (of several, the one that's on). A light group is replaced by its
  members when the switch expands light groups, as Adaptive Lighting
  does.
- Omitted options follow the switch (its adapt switches,
  `prefer_rgb_color` and `initial_transition`), and settings are for
  when the transition ends, as for the regular adaptation. Manual
  control and whether the lights are on don't change the calls.
- The calls are built by the same code as Adaptive Lighting's own,
  factored out of `prepare_adaptation_data` (`_build_service_data`) and
  `adaptation_utils.prepare_adaptation_data` (`plan_service_calls`),
  without changing their behaviour. `SunLightSettings.get_settings`
  takes an optional time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 12:41:40 +03:00

267 lines
14 KiB
Markdown
Raw Blame History

---
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
<!-- CODE:START -->
<!-- from adaptive_lighting._docs_helpers import generate_apply_markdown_table -->
<!-- print(generate_apply_markdown_table()) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
| Service data attribute | Description | Required | Type |
|:-------------------------|:--------------------------------------------------------------------------------------|:-----------|:---------------------|
| `entity_id` | The `entity_id` of the switch with the settings to apply. 📝 | ❌ | list of `entity_id`s |
| `lights` | A light (or list of lights) to apply the settings to. 💡 | ❌ | list of `entity_id`s |
| `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 |
<!-- OUTPUT:END -->
### Example Usage
```yaml
# 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
```
```yaml
# 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
<!-- CODE:START -->
<!-- from adaptive_lighting._docs_helpers import generate_get_commands_markdown_table -->
<!-- print(generate_get_commands_markdown_table()) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
| Service data attribute | Description | Required | Type |
|:-------------------------|:----------------------------------------------------------------------------------------------------------------------|:-----------|:---------------------|
| `entity_id` | The `entity_id` of the switch whose settings to use. 📝 | ❌ | list of `entity_id`s |
| `lights` | Lights or light groups in the switch's `lights` to get the commands for. 💡 | ❌ | list of `entity_id`s |
| `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 |
<!-- OUTPUT:END -->
<!-- CODE:START -->
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
<!-- print(_transform_readme_links(include_section("../README.md", "get-commands"))) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
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:
```yaml
# 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 }}"
```
<!-- OUTPUT:END -->
---
## 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
<!-- CODE:START -->
<!-- from adaptive_lighting._docs_helpers import generate_set_manual_control_markdown_table -->
<!-- print(generate_set_manual_control_markdown_table()) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
| 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_id`s |
| `lights` | entity_id(s) of lights, if not specified, all lights in the switch are selected. 💡 | ❌ | list of `entity_id`s |
| `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']` |
<!-- OUTPUT:END -->
### Example Usage
```yaml
# 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
```
```yaml
# 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
```
```yaml
# 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
<!-- CODE:START -->
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
<!-- print(_transform_readme_links(include_section("../README.md", "change-switch-settings", strip_heading=True))) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
`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. |
<!-- OUTPUT:END -->
### Example Usage
```yaml
# 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
```
```yaml
# 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
```
```yaml
# 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
```yaml
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](automation-examples.md) for more use cases.
Reference in a new issue View git blame Copy permalink