adaptive-lighting/docs/advanced/brightness-modes.md

---
icon: lucide/trending-up
---

# Brightness Modes

Enhance your control over brightness transitions during sunrise and sunset with the `brightness_mode` option.

## Available Modes

Adaptive Lighting supports three brightness modes:

| Mode | Description |
|------|-------------|
| `default` | Standard behavior based on sun position |
| `linear` | Linear ramp between min/max brightness |
| `tanh` | Smooth S-curve using hyperbolic tangent |

## Detailed Explanation

<!-- CODE:START -->
<!-- import sys; sys.path.insert(0, 'custom_components/adaptive_lighting') -->
<!-- from docs_gen import get_brightness_modes -->
<!-- print(get_brightness_modes()) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
<details>
<summary>Enhance your control over brightness transitions during sunrise and sunset with <code>brightness_mode</code> (click here to learn more 🧠).</summary>

With Adaptive Lighting, you can set a `brightness_mode` to specify how the brightness changes during sunrise and sunset. The `brightness_mode` can be set to `"default"` ([as illustrated in other graphs above](#high_brightness-brightness)), `"linear"`, or `"tanh"`. If you choose to deviate from the `"default"` mode, you can adjust `brightness_mode_time_dark` and `brightness_mode_time_light` to further customize the lighting transitions.

When `brightness_mode` is set to `"linear"`:

- During **_sunset_**, the brightness begins to gradually decrease from `max_brightness` starting at `time=sunset_time - brightness_mode_time_light`, until it reaches `min_brightness` at `time=sunset_time + brightness_mode_time_dark`.
- During **_sunrise_**, the brightness begins to gradually increase from `min_brightness` starting at `time=sunrise_time - brightness_mode_time_dark`, until it reaches `max_brightness` at `time=sunrise_time + brightness_mode_time_light`.

When `brightness_mode` is set to `"tanh"`, it uses the smooth transition of a [hyperbolic tangent function](https://mathworld.wolfram.com/HyperbolicTangent.html):

- During **_sunset_**, the brightness starts to decrease from 95% of `max_brightness` starting at `time=sunset_time - brightness_mode_time_light`, until it reaches 5% of `min_brightness` at `time=sunset_time + brightness_mode_time_dark`.
- During **_sunrise_**, the brightness starts to increase from 5% of `min_brightness` starting at `time=sunrise_time - brightness_mode_time_dark`, until it reaches 95% of `max_brightness` at `time=sunrise_time + brightness_mode_time_light`.
</details>

Notice the values of `brightness_mode_time_light` and `brightness_mode_time_dark` in the text box.
![image](https://github.com/basnijholt/adaptive-lighting/assets/6897215/15143580-13cd-4ab2-a603-89f2b7830afd)
![image](https://github.com/basnijholt/adaptive-lighting/assets/6897215/f61fdac9-6d47-48c9-84ed-cbb451d5de5d)
![image](https://github.com/basnijholt/adaptive-lighting/assets/6897215/e5fc5d27-3c37-4e3d-93d1-6e7cf4b48e7c)
![image](https://github.com/basnijholt/adaptive-lighting/assets/6897215/3dcbdc42-63c4-49df-8651-d2fae53dd08d)

> Check out the interactive webapp on https://basnijholt.github.io/adaptive-lighting/ to play with the parameters and see how the brightness changes!

<!-- OUTPUT:END -->

## Configuration Parameters

When using `linear` or `tanh` modes, you can fine-tune the transition with these parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `brightness_mode_time_dark` | 900 (15 min) | Duration to ramp brightness before/after sunrise/sunset |
| `brightness_mode_time_light` | 3600 (1 hour) | Duration to ramp brightness after/before sunrise/sunset |

## Example Configurations

### Quick Transition (Linear)

```yaml
adaptive_lighting:
  - name: "Quick transitions"
    lights:
      - light.living_room
    brightness_mode: linear
    brightness_mode_time_dark: 600    # 10 minutes
    brightness_mode_time_light: 1800  # 30 minutes
```

### Smooth Transition (Tanh)

```yaml
adaptive_lighting:
  - name: "Smooth transitions"
    lights:
      - light.bedroom
    brightness_mode: tanh
    brightness_mode_time_dark: 1200   # 20 minutes
    brightness_mode_time_light: 3600  # 1 hour
```

## Graphs

These graphs show how brightness changes throughout the day based on calculated values:

<!-- CODE:START -->
<!-- import sys; sys.path.insert(0, 'custom_components/adaptive_lighting') -->
<!-- from docs_gen import get_graphs -->
<!-- print(get_graphs()) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
These graphs were generated using the values calculated by the Adaptive Lighting sensor/switch(es).

### :sunny: Sun Position
![cl_percent|690x131](https://community-home-assistant-assets.s3.dualstack.us-west-2.amazonaws.com/original/3X/6/5/657ff98beb65a94598edeb4bdfd939095db1a22c.PNG)

### :thermometer: Color Temperature
![cl_color_temp|690x129](https://community-home-assistant-assets.s3.dualstack.us-west-2.amazonaws.com/original/3X/5/9/59e84263cbecd8e428cb08777a0413672c48dfcd.PNG)

### :high_brightness: Brightness
![cl_brightness|690x130](https://community-home-assistant-assets.s3.dualstack.us-west-2.amazonaws.com/original/3X/5/8/58ebd994b62a8b1abfb3497a5288d923ff4e2330.PNG)

### While using `transition_until_sleep: true`
![image](https://user-images.githubusercontent.com/2219836/228949675-f9699624-8abc-466c-bb04-250ce0f495b8.png)

<!-- OUTPUT:END -->

## Interactive Simulator

The best way to understand brightness modes is to experiment with the interactive simulator:

<div style="text-align: center; margin: 2rem 0;">
  <a href="../simulator/" class="simulator-link">
    🌞 Try the Simulator 🌛
  </a>
</div>

Adjust the `brightness_mode`, `brightness_mode_time_dark`, and `brightness_mode_time_light` parameters to see how they affect the brightness curve in real-time.