DOCSEARCHbyAlgolia
Submit Docs

Adaptive Lighting

repository·main·Indexed 25 days ago

https://github.com/basnijholt/adaptive-lighting

A Home Assistant custom component (version 1.30.1) that synchronizes smart lighting brightness and color temperature with the sun's position to support natural circadian rhythms. It provides features such as sleep mode, manual control detection, and customizable brightness modes (default, linear, and tanh) to manage transitions during sunrise and sunset.

Tokens
9.5K
Snippets
21
Records
47
Agent score
83%

What's inside adaptive-lighting

  1. Understand Adaptive Lighting Features and Switches

    main

    Adaptive Lighting automatically adjusts light brightness and color based on the sun's position. For every component configured (e.g., living_room), the integration provides four specific switches to control its behavior:

    • switch.adaptive_lighting_<component_name>: Toggles the Adaptive Lighting logic for that component and allows viewing current light settings via attributes.
    • switch.adaptive_lighting_sleep_mode_<component_name>: Activates "sleep mode", which applies custom sleep_brightness and sleep_color_temp settings.
    • switch.adaptive_lighting_adapt_brightness_<component_name>: Enables or disables brightness adaptation for the lights in that component.
    • switch.adaptive_lighting_adapt_color_<component_name>: Enables or disables color adaptation for the lights in that component.

  2. Learn about Adaptive Lighting through tutorials

    main

    The following external resources provide guidance on setting up and using Adaptive Lighting:

  3. Enable debug logging for Adaptive Lighting

    main

    To troubleshoot issues, enable debug logging in your Home Assistant configuration.yaml file. This will allow you to capture detailed logs in /config/home-assistant.log which are necessary for reporting issues on GitHub.

    logger:
  default: warning
  logs:
    custom_components.adaptive_lighting: debug

  4. Configure brightness modes for sunrise and sunset

    main

    Use the brightness_mode option to control how brightness transitions occur during sunrise and sunset.

    Available Modes

    • default: Standard behavior based on sun position.
    • linear: A linear ramp between min_brightness and max_brightness.
    • tanh: A smooth S-curve transition using a hyperbolic tangent function.

    Transition Timing

    When using linear or tanh modes, you can customize the transition duration using these parameters:

    • brightness_mode_time_dark: The duration (in seconds) to ramp brightness before/after sunrise/sunset. Default is 900 (15 min).
    • brightness_mode_time_light: The duration (in seconds) to ramp brightness after/before sunrise/sunset. Default is 3600 (1 hour).

    Mode Behavior Details

    • linear mode:
      • Sunset: Decreases from max_brightness starting at sunset_time - brightness_mode_time_light until it reaches min_brightness at sunset_time + brightness_mode_time_dark.
      • Sunrise: Increases from min_brightness starting at sunrise_time - brightness_mode_time_dark until it reaches max_brightness at sunrise_time + brightness_mode_time_light.
    • tanh mode:
      • Sunset: Decreases from 95% of max_brightness starting at sunset_time - brightness_mode_time_light until it reaches 5% of min_brightness at sunset_time + brightness_mode_time_dark.
      • Sunrise: Increases from 5% of min_brightness starting at sunrise_time - brightness_mode_time_dark until it reaches 95% of max_brightness at sunrise_time + brightness_mode_time_light.

  5. Configure Adaptive Lighting in Home Assistant

    main

    Follow these steps to set up the integration:

    1. Add to configuration.yaml

    You must add the adaptive_lighting: entry to your configuration.yaml file, even if you intend to use the UI for all subsequent configuration.

    2. Restart Home Assistant

    Restart Home Assistant to load the new component.

    3. Add the Integration

    1. Navigate to Settings → Devices & Services.
    2. Click + Add Integration.
    3. Search for "Adaptive Lighting".
    4. Follow the setup wizard to select your lights.

    4. Configure Your Lights

    You can configure settings via the UI or via YAML.

    adaptive_lighting:

  6. Run the Adaptive Lighting webapp locally

    main

    To run the webapp interface on your local machine, navigate to the webapp directory, install the development dependencies using pip, and start the server using the shiny CLI. Once the server is running, access the interface via your web browser at http://127.0.0.1:8000.

    $ cd webapp
$ pip install -r requirements-dev.txt
$ shiny run

  8. Resolve light color temperature mismatches

    main

    Bulbs from different manufacturers may have different color temperature specifications. To ensure consistent colors:

    1. Include only bulbs of the same make and model in a single Adaptive Lighting configuration.
    2. Arrange bulbs so that different color temperatures are not visible in the same space simultaneously.

  9. Install Adaptive Lighting via HACS (Recommended)

    main

    The recommended way to install Adaptive Lighting is through the Home Assistant Community Store (HACS):

    1. Open HACS in your Home Assistant instance.
    2. Click on Integrations.
    3. Click the + Explore & Download Repositories button.
    4. Search for "Adaptive Lighting".
    5. Click Download.
    6. Restart Home Assistant.

  10. Regain Manual Control of Lights

    main

    Adaptive Lighting detects manual changes to light settings (via UI or automation) and marks the light as "manually controlled" to prevent further automatic adjustments. This behavior is active when take_over_control is enabled.

    To resume automatic control after a manual change, you must either:

    1. Turn the light off and back on.
    2. Call the adaptive_lighting.set_manual_control service to reset the manual control state.

    If you need to detect changes made outside of Home Assistant (e.g., via a physical switch), enable the detect_non_ha_changes option.

    Caution: Some lights may falsely report an 'on' state. If your lights turn on unexpectedly, disable detect_non_ha_changes.

  11. Configure Adaptive Lighting via YAML or UI

    main

    Adaptive Lighting can be configured using either your Home Assistant configuration.yaml file or the Home Assistant frontend (Settings -> Devices and Services -> Adaptive Lighting -> Options).

    Important: Even if you intend to use the UI for all configuration, you must still add the base adaptive_lighting: entry to your configuration.yaml to initialize the integration.

    # Example configuration.yaml entry
adaptive_lighting:
  lights:
    - light.living_room_lights

  12. Install and set up Adaptive Lighting in Home Assistant

    main

    Adaptive Lighting is a Home Assistant custom component that adjusts light brightness and color based on the sun's position. Follow these steps to install it:

    1. Install via HACS: Search for "Adaptive Lighting" in the Home Assistant Community Store (HACS).
    2. Add to configuration: Add the adaptive_lighting: entry to your configuration.yaml file. Even if you intend to use the UI for all other configurations, this entry is required.
    3. Configure via UI: Go to Settings → Devices & Services → Add Integration → Adaptive Lighting.
    4. Select lights: Choose the lights you want the integration to control.
    # Minimal configuration.yaml entry
adaptive_lighting:
  lights:
    - light.living_room