mirror of
https://github.com/basnijholt/adaptive-lighting.git
synced 2026-09-12 14:54:04 +02:00
cbbcabdd1f* Add documentation site with Zensical framework
Create comprehensive documentation site for adaptive-lighting.nijho.lt:
- Add zensical.toml configuration with Material theme (amber/orange)
- Create docs_gen.py module for extracting README sections via markers
- Add section markers to README.md for content reuse
- Create documentation pages:
- index.md: Home with features overview
- getting-started.md: Installation and quick setup
- configuration.md: Auto-generated config options table
- services.md: Auto-generated service documentation
- automation-examples.md: Real-world automation recipes
- troubleshooting.md: Common issues and solutions
- see-also.md: External resources and links
- advanced/brightness-modes.md: Brightness mode deep dive
- advanced/manual-control.md: Manual control system docs
- advanced/sleep-mode.md: Sleep mode configuration
- Add GitHub Actions workflow for building and deploying to Pages
- Add custom CSS with sun-themed styling
- Add CNAME for custom domain
Uses markdown-code-runner to auto-generate content from code schemas
and extract README sections for single-source documentation.
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Remove duplicated content from docs, make pages thin wrappers
- troubleshooting.md: Remove manually written "Additional Tips" section
- automation-examples.md: Remove duplicate "Additional Examples" section
- configuration.md: Remove duplicate "Option Categories" tables
- sleep-mode.md: Simplify to reference main config, remove duplicate examples
- docs_gen.py: Remove unused get_troubleshooting() and get_sleep_mode_intro()
This reduces duplication risk by keeping README as single source of truth.
Docs pages now primarily pull content via markdown-code-runner.
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Integrate webapp (simulator) into docs workflow
- Merge deploy-webapp.yml into docs.yml workflow
- Build simulator and place at /simulator/ subdirectory
- Update docs links to use relative paths to simulator
- Remove separate deploy-webapp.yml to avoid conflicts
The combined workflow now:
1. Builds docs with zensical
2. Builds webapp with shinylive
3. Copies webapp to site/simulator/
4. Deploys everything to GitHub Pages
Simulator will be at adaptive-lighting.nijho.lt/simulator/
* Fix pre-commit and CI issues
- Add site_name to zensical.toml (required by MkDocs)
- Fix RET504 in docs_gen.py (unnecessary assignment before return)
- Remove docs/run_markdown_code_runner.py (lint issues, not needed for CI)
* Fix _docs_helpers.py import error in CI
- Add try/except for relative vs absolute imports in _docs_helpers.py
- Remove silent error handling in docs workflow (fail on error)
The relative import fails when markdown-code-runner executes the code
directly via sys.path.insert. The fallback to absolute import fixes this.
* Temporarily enable deployment from feature branch
* Add tabulate dependency for pandas to_markdown()
* Fix theme configuration for proper light/dark mode
- Restructure zensical.toml to match working agent-cli config
- Add three-way palette toggle (system/light/dark)
- Use proper [project.theme] structure
- Simplify extra.css to not override theme colors
- Add Inter font for text, JetBrains Mono for code
* Add Plausible analytics and fix homepage navigation
- Add custom analytics override for plausible.nijho.lt tracking
- Remove hide:navigation from index.md to show menu on homepage
* Remove temporary feature branch deployment settings
Revert to main-only deployment for docs workflow before merging.
* Revert "Remove temporary feature branch deployment settings"
This reverts commit c568694837.
* Add markdown-gfm-admonition for GitHub-style admonitions
The zensical build was failing silently because gfm_admonition extension
was not installed. Add the dependency to pyproject.toml and docs workflow.
* Use uv sync for documentation dependencies
Switch from manual pip installs to uv sync with pyproject.toml for cleaner
dependency management and reproducible builds.
* Fix markdown rendering inside details blocks
Enable md_in_html extension and add markdown="1" attribute to <details>
tags so markdown content inside them is properly rendered.
* Remove emojis from manually written documentation
Keep emojis in auto-generated content from README, but remove from
manually maintained docs in favor of clean text and Material icons.
* Enable attr_list extension for button styling
* Improve pyproject.toml and use GitHub-style admonitions
- Add accurate project metadata (version, authors, classifiers, URLs)
- Organize dependency groups: docs, dev, test
- Add tool configs for ruff, mypy, pytest
- Convert MkDocs-style admonitions (!!! tip) to GitHub-style (> [!TIP])
- Use docs group in CI workflow
* Add homeassistant and ulid-transform as runtime dependencies
Remove speculative test dependencies since tests run inside HA core.
* Simplify docs_gen.py - remove wrapper functions
Use readme_section() directly in docs instead of 10 one-liner wrappers.
Changed default strip_heading to True since that's the common case.
* Populate empty OUTPUT sections with markdown-code-runner
* Add markdown-code-runner workflow for auto-updating docs
- Add docs/run_markdown_code_runner.py script to process all docs
- Add GitHub workflow to run on push/PR and auto-commit changes
* Exclude README.md from markdown-code-runner workflow
README.md contains code blocks that import from
homeassistant.components.adaptive_lighting, which only exists
when running inside Home Assistant core, not in a regular venv.
* Update auto-generated docs
* Use editable install for markdown-code-runner workflow
- Add setuptools.packages.find config pointing to custom_components
- Remove sys.path.insert manipulation from all docs files
- Update imports to use adaptive_lighting.* package paths
- Install package with `uv pip install -e .` in workflow
- Remove deprecated license classifier (PEP 639)
* Consolidate markdown-code-runner into single workflow
- Remove separate markdown-code-runner.yml workflow
- Update update-readme.yml to handle all markdown files (docs + README)
- Rename workflow to "Update auto-generated content"
- Update README imports to use adaptive_lighting package path
* Rename workflow to markdown-code-runner
* Remove accidentally committed files
* Remove redundant markdown-code-runner from docs workflow
* Fix: use uv pip install instead of uv add in CI
* Add webapp deps (astral, shinylive) to docs group
* Remove unused install_dependencies action
* Update to latest action versions (uv@v5, upload-pages-artifact@v4)
* Remove try/except import fallback in _docs_helpers.py
* Restore install_dependencies action (used by pytest)
* Simplify docs workflow: run on all pushes/PRs
* Simplify mcr workflow paths; revert install_dependencies to main
* Remove redundant cp+sed for webapp (file already in repo)
* Fix mcr push: pull --rebase before push
* Fix mcr: checkout PR branch instead of detached HEAD
* Update auto-generated content
* Switch from setuptools to hatch build system
Replace [tool.setuptools.packages.find] with [tool.hatch.build.targets.wheel]
for hatchling compatibility.
* Update auto-generated content
* Move homeassistant deps to docs group
This is a HA custom component, not a pip package. The homeassistant
dependency is only needed for docs building, not as a project dependency.
* Update auto-generated content
* Remove PyPI-only metadata from pyproject.toml
* Remove arbitrary version constraints from dependency groups
* Update auto-generated content
* Remove unused troubleshooting section markers from README
* Remove temporary feature branch settings from docs workflow
* Use GitHub admonition syntax for warning in change_switch_settings section
* Update auto-generated content
150 lines
22 KiB
Markdown
150 lines
22 KiB
Markdown
---
|
|
icon: lucide/settings
|
|
---
|
|
|
|
# Configuration
|
|
|
|
Adaptive Lighting supports configuration through both YAML and the Home Assistant UI, with identical option names in both methods.
|
|
|
|
## Basic Configuration
|
|
|
|
The minimal configuration requires only adding the integration to your `configuration.yaml`:
|
|
|
|
```yaml
|
|
adaptive_lighting:
|
|
```
|
|
|
|
You can then configure everything through the UI at **Settings** → **Devices & Services** → **Adaptive Lighting** → **Configure**.
|
|
|
|
## YAML Configuration
|
|
|
|
For YAML configuration, you can specify lights and options directly:
|
|
|
|
```yaml
|
|
adaptive_lighting:
|
|
- name: "Living Room"
|
|
lights:
|
|
- light.living_room_ceiling
|
|
- light.living_room_lamp
|
|
```
|
|
|
|
## All Options
|
|
|
|
All configuration options are listed below with their default values. These options work identically in both YAML and the UI.
|
|
|
|
<!-- CODE:START -->
|
|
<!-- from adaptive_lighting._docs_helpers import generate_config_markdown_table -->
|
|
<!-- print(generate_config_markdown_table()) -->
|
|
<!-- CODE:END -->
|
|
<!-- OUTPUT:START -->
|
|
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
|
|
| Variable name | Description | Default | Type |
|
|
|:-------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------|:----------------------------------------|
|
|
| `lights` | List of light entity_ids to be controlled (may be empty). 🌟 | `[]` | list of `entity_id`s |
|
|
| `interval` | Frequency to adapt the lights, in seconds. 🔄 | `90` | `int > 0` |
|
|
| `transition` | Duration of transition when lights change, in seconds. 🕑 | `45` | `float` 0-6553 |
|
|
| `initial_transition` | Duration of the first transition when lights turn from `off` to `on` in seconds. ⏲️ | `1` | `float` 0-6553 |
|
|
| `min_brightness` | Minimum brightness percentage. 💡 | `1` | `int` 1-100 |
|
|
| `max_brightness` | Maximum brightness percentage. 💡 | `100` | `int` 1-100 |
|
|
| `min_color_temp` | Warmest color temperature in Kelvin. 🔥 | `2000` | `int` 1000-10000 |
|
|
| `max_color_temp` | Coldest color temperature in Kelvin. ❄️ | `5500` | `int` 1000-10000 |
|
|
| `prefer_rgb_color` | Whether to prefer RGB color adjustment over light color temperature when possible. 🌈 | `False` | `bool` |
|
|
| `sleep_brightness` | Brightness percentage of lights in sleep mode. 😴 | `1` | `int` 1-100 |
|
|
| `sleep_rgb_or_color_temp` | Use either `"rgb_color"` or `"color_temp"` in sleep mode. 🌙 | `color_temp` | one of `['color_temp', 'rgb_color']` |
|
|
| `sleep_color_temp` | Color temperature in sleep mode (used when `sleep_rgb_or_color_temp` is `color_temp`) in Kelvin. 😴 | `1000` | `int` 1000-10000 |
|
|
| `sleep_rgb_color` | RGB color in sleep mode (used when `sleep_rgb_or_color_temp` is "rgb_color"). 🌈 | `[255, 56, 0]` | RGB color |
|
|
| `sleep_transition` | Duration of transition when "sleep mode" is toggled in seconds. 😴 | `1` | `float` 0-6553 |
|
|
| `transition_until_sleep` | When enabled, Adaptive Lighting will treat sleep settings as the minimum, transitioning to these values after sunset. 🌙 | `False` | `bool` |
|
|
| `sunrise_time` | Set a fixed time (HH:MM:SS) for sunrise. 🌅 | `None` | `str` |
|
|
| `min_sunrise_time` | Set the earliest virtual sunrise time (HH:MM:SS), allowing for later sunrises. 🌅 | `None` | `str` |
|
|
| `max_sunrise_time` | Set the latest virtual sunrise time (HH:MM:SS), allowing for earlier sunrises. 🌅 | `None` | `str` |
|
|
| `sunrise_offset` | Adjust sunrise time with a positive or negative offset in seconds. ⏰ | `0` | `int` |
|
|
| `sunset_time` | Set a fixed time (HH:MM:SS) for sunset. 🌇 | `None` | `str` |
|
|
| `min_sunset_time` | Set the earliest virtual sunset time (HH:MM:SS), allowing for later sunsets. 🌇 | `None` | `str` |
|
|
| `max_sunset_time` | Set the latest virtual sunset time (HH:MM:SS), allowing for earlier sunsets. 🌇 | `None` | `str` |
|
|
| `sunset_offset` | Adjust sunset time with a positive or negative offset in seconds. ⏰ | `0` | `int` |
|
|
| `brightness_mode` | Brightness mode to use. Possible values are `default`, `linear`, and `tanh` (uses `brightness_mode_time_dark` and `brightness_mode_time_light`). 📈 | `default` | one of `['default', 'linear', 'tanh']` |
|
|
| `brightness_mode_time_dark` | (Ignored if `brightness_mode='default'`) The duration in seconds to ramp up/down the brightness before/after sunrise/sunset. 📈📉 | `900` | `int` |
|
|
| `brightness_mode_time_light` | (Ignored if `brightness_mode='default'`) The duration in seconds to ramp up/down the brightness after/before sunrise/sunset. 📈📉. | `3600` | `int` |
|
|
| `take_over_control` | Pause adaptation of individual lights and hand over (manual) control to other sources that issue `light.turn_on` calls for lights that are on. 🔒 | `True` | `bool` |
|
|
| `take_over_control_mode` | The adaptation pausing mode when other sources change brightness and/or color of lights. `pause_all` always pauses both brightness and color adaptation. `pause_changed` pauses the adaptation of only the changed attributes and continues adapting unchanged attributes, e.g., continues color adaptation when only brightness was changed. | `pause_all` | one of `['pause_all', 'pause_changed']` |
|
|
| `detect_non_ha_changes` | Detects and halts adaptations for non-`light.turn_on` state changes. Needs `take_over_control` enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Note that this calls `homeassistant.update_entity` every `interval`! Disable this feature if you encounter such issues. | `False` | `bool` |
|
|
| `autoreset_control_seconds` | Automatically reset the manual control after a number of seconds. Set to 0 to disable. ⏲️ | `0` | `int` 0-31536000 |
|
|
| `only_once` | Adapt lights only when they are turned on (`true`) or keep adapting them (`false`). 🔄 | `False` | `bool` |
|
|
| `adapt_only_on_bare_turn_on` | When turning lights on initially. If set to `true`, AL adapts only if `light.turn_on` is invoked without specifying color or brightness. ❌🌈 This e.g., prevents adaptation when activating a scene and marks the light as manually controlled. If `false`, AL adapts regardless of the presence of color or brightness in the initial `service_data`. Needs `take_over_control` enabled. 🕵️ | `False` | `bool` |
|
|
| `separate_turn_on_commands` | Use separate `light.turn_on` calls for color and brightness, needed for some light types. 🔀 | `False` | `bool` |
|
|
| `send_split_delay` | Delay (ms) between `separate_turn_on_commands` for lights that don't support simultaneous brightness and color setting. ⏲️ | `0` | `int` 0-10000 |
|
|
| `adapt_delay` | Wait time (seconds) between light turn on and Adaptive Lighting applying changes. Might help to avoid flickering. ⏲️ | `0` | `float > 0` |
|
|
| `skip_redundant_commands` | Skip sending adaptation commands whose target state already equals the light's known state. Minimizes network traffic and improves the adaptation responsivity in some situations. 📉Disable if physical light states get out of sync with HA's recorded state. | `False` | `bool` |
|
|
| `intercept` | Intercept and adapt `light.turn_on` calls to enabling instantaneous color and brightness adaptation. 🏎️ Disable for lights that do not support `light.turn_on` with color and brightness. | `True` | `bool` |
|
|
| `multi_light_intercept` | Intercept and adapt `light.turn_on` calls that target multiple lights. ➗⚠️ This might result in splitting up a single `light.turn_on` call into multiple calls, e.g., when lights are in different switches. Requires `intercept` to be enabled. | `True` | `bool` |
|
|
| `include_config_in_attributes` | Show all options as attributes on the switch in Home Assistant when set to `true`. 📝 | `False` | `bool` |
|
|
|
|
<!-- OUTPUT:END -->
|
|
|
|
## Full Configuration Example
|
|
|
|
<!-- CODE:START -->
|
|
<!-- from adaptive_lighting.docs_gen import readme_section -->
|
|
<!-- print(readme_section("config-example-full", strip_heading=False)) -->
|
|
<!-- CODE:END -->
|
|
<!-- OUTPUT:START -->
|
|
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
|
|
Full example:
|
|
|
|
```yaml
|
|
# Example configuration.yaml entry
|
|
adaptive_lighting:
|
|
- name: "default"
|
|
lights: []
|
|
prefer_rgb_color: false
|
|
transition: 45
|
|
initial_transition: 1
|
|
interval: 90
|
|
min_brightness: 1
|
|
max_brightness: 100
|
|
min_color_temp: 2000
|
|
max_color_temp: 5500
|
|
sleep_brightness: 1
|
|
sleep_color_temp: 1000
|
|
sunrise_time: "08:00:00" # override the sunrise time
|
|
sunrise_offset:
|
|
sunset_time:
|
|
sunset_offset: 1800 # in seconds or '00:30:00'
|
|
take_over_control: true
|
|
detect_non_ha_changes: false
|
|
only_once: false
|
|
|
|
```
|
|
|
|
<!-- OUTPUT:END -->
|
|
|
|
## Multiple Configurations
|
|
|
|
You can create multiple Adaptive Lighting configurations for different areas or use cases:
|
|
|
|
```yaml
|
|
adaptive_lighting:
|
|
- name: "Daytime Spaces"
|
|
lights:
|
|
- light.living_room
|
|
- light.kitchen
|
|
- light.office
|
|
min_brightness: 30
|
|
max_brightness: 100
|
|
|
|
- name: "Bedroom"
|
|
lights:
|
|
- light.bedroom_ceiling
|
|
- light.bedroom_lamp
|
|
min_brightness: 5
|
|
max_brightness: 80
|
|
sleep_brightness: 1
|
|
sleep_color_temp: 1000
|
|
```
|
|
|
|
## Related Topics
|
|
|
|
- [Brightness Modes](advanced/brightness-modes.md) - Detailed explanation of brightness calculation modes
|
|
- [Sleep Mode](advanced/sleep-mode.md) - Sleep mode configuration
|
|
- [Manual Control](advanced/manual-control.md) - How manual control detection works
|