Home Assistant Blueprints

Pro‑grade automation templates for real homes

☕ Like these? Buy me a coffee

---

Overview

This repository hosts polished, production‑ready Home Assistant Blueprints that solve real household needs. Each blueprint is:

• Robust: battle‑tested logic with clear input validation and sane defaults
• Efficient: avoids unnecessary service calls, respects device limits, and reduces chatter
• Configurable: sensible presets with advanced controls when you want them
• Documented: README per blueprint, changelog, and conventional commits
• MIT‑licensed: permissive for personal and commercial use

Blueprints use YAML with Jinja2 templating and follow Semantic Versioning.

Blueprints Gallery

Quickly explore and import blueprints. "Import" buttons link to the YAML on GitHub (blob). For direct import in Home Assistant, use the Raw link in Quick Links.

1) Adaptive Comfort Control Pro

Advanced HVAC automation implementing ASHRAE‑55 adaptive comfort with built‑in psychrometrics (dew point, absolute humidity, enthalpy), vendor auto‑profiles, seasonal bias, CO₂‑aware ventilation, and smart pause acceleration.

Quick Links: Raw • Docs • Changelog

---

2) Bathroom Light Fan Control Pro

Coordinated bathroom light and fan automation with occupancy ("Wasp-in-a-Box"), humidity delta and rate-of-change detection, night mode, and manual override.

Quick Links: Raw • Docs • Changelog

---

3) Multi Switch Light Control Pro

A single automation that adapts to Zooz/Inovelli Central Scene switches or Lutron Pico remotes, auto-detects the selected hardware, and unifies dimming/transition tuning across every trigger.

Quick Links: Raw • Docs • Changelog

---

4) Adaptive Shades Pro

Solar-aware shade control for venetian/vertical slats or zebra shades with direct vs diffuse detection, temperature bands, presence/quiet hours, glare handling, and night close/resume behavior.

Quick Links: Raw • Docs • Changelog

---

5) Ceiling Fan Climate Control Pro

HVAC-aware ceiling fan automation with EN 16798 adaptive comfort model, heat index calculation, deviation-based speed control, occupancy awareness, and optional direction control for seasonal optimization.

Quick Links: Raw • Docs • Changelog

---

Quick Start

1. Click an Import badge above to view the blueprint YAML on GitHub.
2. For Home Assistant's Import dialog, copy the Raw link for your chosen blueprint.
3. In Home Assistant: Settings → Automations & Scenes → Blueprints → Import Blueprint → paste the Raw URL.
4. Create an automation from the blueprint and configure inputs via the UI.
5. Check Traces and Logs if anything looks off.

Design Principles

• Safety first: device vendor limits and unit correctness
• Minimalism: only the inputs you need, with clearly described defaults
• Predictability: deterministic logic and quantization to device step sizes
• Observability: debug levels (off/basic/verbose) and traceable decision paths
• Performance: avoid unnecessary service calls and rate-limit where needed

Repository Structure

.
├── blueprints/
│   ├── adaptive-comfort-control/
│   │   ├── adaptive_comfort_control_pro_blueprint.yaml
│   │   ├── CHANGELOG.md
│   │   ├── LEARNING_SETUP.md
│   │   └── README.md
│   ├── adaptive-fan-control/
│   │   ├── adaptive_fan_control_pro_blueprint.yaml
│   │   ├── CHANGELOG.md
│   │   └── README.md
│   ├── adaptive-shades/
│   │   ├── adaptive_shades_pro.yaml
│   │   ├── CHANGELOG.md
│   │   └── README.md
│   ├── bathroom-light-fan-control/
│   │   ├── bathroom_light_fan_control_pro.yaml
│   │   ├── CHANGELOG.md
│   │   └── README.md
│   ├── multi-switch-light-control/
│   │   ├── multi_switch_light_control_pro.yaml
│   │   ├── CHANGELOG.md
│   │   └── README.md
│   └── shared/                       # Shared resources for blueprints
│       ├── README.md
│       ├── regional_profiles.json    # Climate presets database
│       ├── regional_profile_helpers.yaml
│       └── templates.yaml            # Reusable Jinja2 template macros
├── .github/
│   └── workflows/
│       ├── auto-tag-go-tools.yml  # Auto-tag on Go tool version changes
│       ├── ci-go-tools.yml        # CI for Go tools (lint, test, build)
│       ├── pages.yml              # GitHub Pages deployment
│       ├── release-go-tools.yml   # Release binaries on version tags
│       └── validate-blueprints.yml # Blueprint validation CI
├── scripts/
│   ├── ha-ws-client-go/          # Home Assistant WebSocket CLI client
│   │   ├── cmd/ha-ws-client/     # CLI entry point
│   │   ├── internal/
│   │   │   ├── client/           # WebSocket client
│   │   │   ├── handlers/         # Command handlers
│   │   │   ├── shutdown/         # Graceful shutdown coordination
│   │   │   ├── output/           # Output formatting
│   │   │   ├── cli/              # CLI utilities
│   │   │   └── types/            # Type definitions
│   │   ├── Makefile
│   │   └── README.md
│   ├── validate-blueprint-go/    # Blueprint validator CLI
│   │   ├── main.go
│   │   ├── internal/
│   │   │   ├── validator/        # Core validation logic
│   │   │   ├── shutdown/         # Graceful shutdown coordination
│   │   │   └── common/           # Shared utilities
│   │   ├── Makefile
│   │   └── README.md
│   ├── go-tools/                 # Shared Go packages for CLI tools
│   │   └── selfupdate/           # Self-update functionality
│   │       ├── checksum.go       # Checksum verification
│   │       ├── errors.go         # Error types
│   │       ├── github.go         # GitHub API client
│   │       ├── platform.go       # Platform detection
│   │       ├── progress.go       # Download progress display
│   │       ├── selfupdate.go     # Core update logic
│   │       └── version.go        # Version parsing
│   ├── testfixtures/             # Shared test fixtures for Go tools
│   │   ├── blueprint_fixtures.go # Blueprint test data
│   │   ├── ha_fixtures.go        # Home Assistant test data
│   │   ├── ws_server.go          # Mock WebSocket server
│   │   └── types.go              # Shared test types
│   └── shared.mk                 # Shared Makefile definitions
└── README.md (this file)

Troubleshooting & Debugging

• Enable the blueprint's Debug level (basic or verbose) to see key decisions and sensor values.
• Units matter: internal calcs often in °C; thermostats may be °F. Ensure conversions and quantization align with device step sizes.
• Optional sensors: guard against unavailable/unknown/none states.
• State/trigger race conditions: add small delays (e.g., 100ms) if a change should settle before the next action.
• Use entity selectors (not target selectors) for triggers; use !input directly in trigger for: durations.

Contributing

Contributions are welcome!

Development setup:

make setup              # One-command setup (pre-commit, Go tools, docs)
# Or manually:
pip install pre-commit  # Install pre-commit
pre-commit install      # Set up git hooks
make build              # Build Go validation tools

This sets up pre-commit hooks that validate blueprints and enforce conventional commits.

Conventional Commits required (examples):

• docs(readme): clarify quick start
• feat(bathroom): add night mode brightness floor
• fix(adaptive-comfort): correct °F step quantization

Semantic Versioning per blueprint:

• MAJOR: breaking changes
• MINOR: new features
• PATCH: bug fixes

Open a PR with a clear description and tests/trace screenshots when relevant.

License

MIT — see the LICENSE file. You can use these blueprints in personal or commercial projects.

Support

If these blueprints help you, consider supporting:

• ☕ Buy Me A Coffee: https://buymeacoffee.com/schoolboyqueue

---

Star History