mirror of
https://github.com/basnijholt/adaptive-lighting.git
synced 2026-10-29 06:37:13 +01:00
54a821cc4c
Apply the settings Adaptive Lighting would use at a given time of day (today) instead of now, e.g. to switch a room to its evening settings early. The adapted attributes are marked as manually controlled, like a manual change in Home Assistant, so the regular adaptation keeps its hands off until manual control is reset. They are marked before the adaptation, so a regular adaptation can't slip in between and overwrite the values. Sleep mode takes precedence, and the switch's own settings and attributes are left untouched. `prepare_adaptation_data` no longer writes the switch's settings: it did so only to have values to read when the switch was off, and now uses the settings it calculates itself. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
217 lines
10 KiB
Markdown
217 lines
10 KiB
Markdown
---
|
|
icon: lucide/zap
|
|
---
|
|
|
|
# Services
|
|
|
|
Adaptive Lighting provides three 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 |
|
|
| `time` | Manually apply the settings for this time of day (HH:MM:SS) instead of now. 🕰️ | ❌ | time (HH:MM:SS) |
|
|
|
|
<!-- 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
|
|
```
|
|
|
|
```yaml
|
|
# Set the lights to this evening's 22:00 settings and hold them there
|
|
service: adaptive_lighting.apply
|
|
data:
|
|
entity_id: switch.adaptive_lighting_living_room
|
|
lights:
|
|
- light.sofa
|
|
- light.floor_lamp
|
|
time: "22:00:00"
|
|
```
|
|
|
|
With `time`, the lights get the values Adaptive Lighting would use at that time today. The adapted attributes are then marked as manually controlled, exactly as if you had changed them yourself: the regular adaptation leaves them alone until manual control is reset (for example by `autoreset_control_seconds` or `adaptive_lighting.set_manual_control`), and an `adaptive_lighting.manual_control` event is fired. When sleep mode is on, the sleep settings are applied instead, whatever the time.
|
|
|
|
---
|
|
|
|
## 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.
|