adaptive-lighting/docs/services.md

---
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.