mirror of
https://github.com/basnijholt/adaptive-lighting.git
synced 2026-09-11 22:34:04 +02:00
623dd65aef* Register service actions in async_setup for Bronze tier compliance - Move 'apply' and 'set_manual_control' service registration from async_setup_entry to async_setup. - Move service handlers to module-level functions in switch.py. - Update apply_service_schema to support dynamic defaults for transition duration. - Clean up related unused imports and fix Python 3.10 syntax compatibility. * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Clean up and add tests * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Fix lint errors * Automated update of generated docs * Re-add types * Make transition not required again * fix: validate global service targets * fix: document optional apply transition * fix: derive service docs from schema markers * docs: clarify service target options * fix: preserve entity service target handling --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Bas Nijholt <bas@nijho.lt>
203 lines
9.6 KiB
Markdown
203 lines
9.6 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 |
|
|
|
|
<!-- 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.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.
|