adaptive-lighting/docs/automation-examples.md

115 lines
3.7 KiB
Markdown
Raw Normal View History

Add documentation site with Zensical framework (#1385) * 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 c56869483760051599234b820b3cf44de128901f. * 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
2026-01-12 23:39:57 +01:00
---
icon: lucide/bot
---
# Automation Examples
Real-world automation examples showing how to integrate Adaptive Lighting with your Home Assistant setup.
<!-- CODE:START -->
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
<!-- print(_transform_readme_links(include_section("../README.md", "automation-examples", strip_heading=True))) -->
Add documentation site with Zensical framework (#1385) * 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 c56869483760051599234b820b3cf44de128901f. * 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
2026-01-12 23:39:57 +01:00
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
<details markdown="1">
<summary>Reset the <code>manual_control</code> status of a light after an hour.</summary>
```yaml
- alias: "Adaptive lighting: reset manual_control after 1 hour"
mode: parallel
trigger:
platform: event
event_type: adaptive_lighting.manual_control
variables:
light: "{{ trigger.event.data.entity_id }}"
switch: "{{ trigger.event.data.switch }}"
action:
- delay: "01:00:00"
- condition: template
value_template: "{{ light in state_attr(switch, 'manual_control') }}"
- service: adaptive_lighting.set_manual_control
data:
entity_id: "{{ switch }}"
lights: "{{ light }}"
manual_control: false
```
</details>
<details markdown="1">
<summary>Toggle multiple Adaptive Lighting switches to "sleep mode" using an <code>input_boolean.sleep_mode</code>.</summary>
```yaml
- alias: "Adaptive lighting: toggle 'sleep mode'"
trigger:
- platform: state
entity_id: input_boolean.sleep_mode
- platform: homeassistant
event: start # in case the states aren't properly restored
variables:
sleep_mode: "{{ states('input_boolean.sleep_mode') }}"
action:
service: "switch.turn_{{ sleep_mode }}"
entity_id:
- switch.adaptive_lighting_sleep_mode_living_room
- switch.adaptive_lighting_sleep_mode_bedroom
```
Set your sunrise and sunset time based on your alarm. The below script sets sunset_time exactly 12 hours after the custom sunrise time.
```yaml
iphone_carly_wakeup:
alias: iPhone Carly Wakeup
sequence:
- condition: state
entity_id: input_boolean.carly_iphone_wakeup
state: "off"
- service: input_datetime.set_datetime
target:
entity_id: input_datetime.carly_iphone_wakeup
data:
time: '{{ now().strftime("%H:%M:%S") }}'
- service: input_boolean.turn_on
target:
entity_id: input_boolean.carly_iphone_wakeup
- repeat:
count: >
{{ (states.switch
| map(attribute="entity_id")
| select(">","switch.adaptive_lighting_al_")
| select("<", "switch.adaptive_lighting_al_z")
| join(",")
).split(",") | length }}
sequence:
- service: adaptive_lighting.change_switch_settings
data:
entity_id: switch.adaptive_lighting_al_den_ceilingfan_lights
sunrise_time: '{{ now().strftime("%H:%M:%S") }}'
sunset_time: >
{{ (as_timestamp(now()) + 12*60*60) | timestamp_custom("%H:%M:%S") }}
- service: script.turn_on
target:
entity_id: script.run_wakeup_routine
- service: input_boolean.turn_off
target:
entity_id:
- input_boolean.carly_iphone_winddown
- input_boolean.carly_iphone_bedtime
- service: input_datetime.set_datetime
target:
entity_id: input_datetime.wakeup_time
data:
time: '{{ now().strftime("%H:%M:%S") }}'
- service: script.adaptive_lighting_disable_sleep_mode
mode: queued
icon: mdi:weather-sunset
max: 10
```
</details>
<!-- OUTPUT:END -->
> [!TIP]
> **Have a useful automation?** Share your automation examples by [opening an issue](https://github.com/basnijholt/adaptive-lighting/issues) or submitting a pull request to the README.