mirror of
https://github.com/basnijholt/adaptive-lighting.git
synced 2026-10-30 23:17:49 +01:00
8ba7aabf05
With `skip_redundant_commands`, the calls leave out what the light has when the service is called, so say to make them right away. Also test a split call dropped after the first one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
267 lines
14 KiB
Markdown
267 lines
14 KiB
Markdown
---
|
|
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. With `skip_redundant_commands`, what a light already has is left out, as when Adaptive Lighting adapts it; that compares with the light's state when you call the service, so make the calls right away. Manual control doesn'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.
|