{"id":41912725,"url":"https://github.com/lnagel/hass-ufh-controller","last_synced_at":"2026-02-14T10:06:31.328Z","repository":{"id":332164909,"uuid":"1128306369","full_name":"lnagel/hass-ufh-controller","owner":"lnagel","description":"Home Assistant Underfloor Heating Controller","archived":false,"fork":false,"pushed_at":"2026-02-07T19:30:04.000Z","size":1199,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-08T04:10:22.196Z","etag":null,"topics":["hacs","hacs-integration","heating-control","home-assistant","home-automation","hvac","pid-controller","python","smart-home","thermostat","underfloor-heating"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lnagel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-05T12:50:19.000Z","updated_at":"2026-02-07T14:40:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lnagel/hass-ufh-controller","commit_stats":null,"previous_names":["lnagel/hass-ufh-controller"],"tags_count":10,"template":false,"template_full_name":"ludeeus/integration_blueprint","purl":"pkg:github/lnagel/hass-ufh-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnagel%2Fhass-ufh-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnagel%2Fhass-ufh-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnagel%2Fhass-ufh-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnagel%2Fhass-ufh-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lnagel","download_url":"https://codeload.github.com/lnagel/hass-ufh-controller/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnagel%2Fhass-ufh-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29442337,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T07:24:13.446Z","status":"ssl_error","status_checked_at":"2026-02-14T07:23:58.969Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacs","hacs-integration","heating-control","home-assistant","home-automation","hvac","pid-controller","python","smart-home","thermostat","underfloor-heating"],"created_at":"2026-01-25T16:12:59.250Z","updated_at":"2026-02-14T10:06:31.323Z","avatar_url":"https://github.com/lnagel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Underfloor Heating Controller\r\n\r\n[![GitHub Release](https://img.shields.io/github/v/release/lnagel/hass-ufh-controller?style=flat-square)](https://github.com/lnagel/hass-ufh-controller/releases)\r\n[![License](https://img.shields.io/github/license/lnagel/hass-ufh-controller?style=flat-square)](LICENSE)\r\n[![HACS](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=flat-square)](https://hacs.xyz/)\r\n[![CI](https://img.shields.io/github/actions/workflow/status/lnagel/hass-ufh-controller/checks.yml?branch=main\u0026style=flat-square\u0026label=tests)](https://github.com/lnagel/hass-ufh-controller/actions)\r\n[![codecov](https://codecov.io/gh/lnagel/hass-ufh-controller/branch/main/graph/badge.svg)](https://codecov.io/gh/lnagel/hass-ufh-controller)\r\n\r\n**The only Home Assistant integration designed specifically for hydronic underfloor heating systems.**\r\n\r\nWhile other thermostats adapt radiator or TRV logic to UFH, this integration is built from the ground up to handle UFH's unique characteristics: high thermal mass, slow response times, and the need to coordinate multiple zones sharing a single heat source.\r\n\r\n## Why This Exists\r\n\r\nThe Home Assistant thermostat ecosystem has excellent options for TRVs ([Better Thermostat](https://github.com/KartoffelToby/better_thermostat)), general climate control ([Versatile Thermostat](https://github.com/jmcollin78/versatile_thermostat)), and precise PID control ([Smart Thermostat PID](https://github.com/ScratMan/smart-thermostat-pid)). But hydronic UFH has specific requirements that none address together:\r\n\r\n| Requirement | Generic Solutions | This Integration |\r\n|-------------|-------------------|------------------|\r\n| **Multi-zone heat aggregation** | Each zone fires boiler independently | Zones coordinate through shared heat request |\r\n| **Boiler/heat pump signaling** | Basic on/off or none | Valve pre-opening, quota-aware requests |\r\n| **EMS-ESP boiler integration** | Manual automations required | Native summer mode, DHW detection |\r\n| **Heat accounting** | Not supported | Supply temperature weighted quota allocation |\r\n| **DHW priority handling** | Not supported | Blocks new heating during DHW, captures residual heat |\r\n| **Weather compensation** | Manual automations or none | Built-in heating curve from outdoor sensor |\r\n| **UFH thermal response** | Adapted from radiator/TRV logic | Native PID tuned for slow thermal mass |\r\n\r\n## Key Differentiators\r\n\r\n### Purpose-Built for Hydronic UFH\r\n\r\nThe control algorithm accounts for:\r\n\r\n- **Slow thermal response** - PID tuning defaults optimized for concrete screed\r\n- **Valve scheduling** - 2-hour observation periods prevent rapid cycling\r\n- **Minimum run times** - Protects valves from wear while maintaining efficiency\r\n- **Sensor noise filtering** - EMA smoothing handles noisy wireless sensors (Zigbee, etc.)\r\n\r\n### Native Boiler Coordination\r\n\r\nMultiple zones sharing one heat source need coordination. The controller:\r\n\r\n- **Aggregates zone demands** into a single heat request signal\r\n- **Waits for valves to open** before firing the boiler (configurable delay)\r\n- **Manages quota intelligently** - stops requesting heat before a zone's time expires\r\n- **Supports summer mode** - automatically enables/disables the boiler's heating circuit\r\n\r\n### Heat Accounting\r\n\r\nMulti-zone systems need fair quota allocation. Simply tracking valve-open time penalizes zones that happen to be open when the boiler is cold—they use up quota while receiving less heating benefit.\r\n\r\n- **Supply-temperature normalization** - Quota consumption adjusts to actual supply conditions\r\n- **Single sensor simplicity** - Only needs one manifold supply temperature sensor\r\n- **Automatic fallback** - Works with simple time-based tracking if no sensor configured\r\n\r\nSee [Heat Accounting](docs/heat_accounting.md) for detailed documentation.\r\n\r\n### Weather Compensation\r\n\r\nThe controller supports outdoor temperature compensation via a configurable heating curve:\r\n\r\n- **Heating curve** - Two-point interpolation adjusts supply target based on outdoor conditions\r\n- **Automatic adaptation** - Warmer weather lowers the supply target, reducing energy use\r\n- **Sensor fallback** - Reverts to fixed supply target if outdoor sensor becomes unavailable\r\n\r\nSee [Heating Curve](docs/heating_curve.md) for detailed documentation.\r\n\r\n### EMS-ESP Integration\r\n\r\nFor users with Bosch, Buderus, Nefit, Junkers, or Worcester boilers running [EMS-ESP](https://github.com/emsesp/EMS-ESP32):\r\n\r\n- **Summer mode control** - Disables heating circuit when no zones need heat\r\n- **DHW priority detection** - Blocks new heating cycles during hot water, existing zones continue circulating\r\n- **Residual heat capture** - Flush circuits capture residual heat from the boiler after DHW ends\r\n\r\n### Zone Fault Isolation\r\n\r\nSensor failures in one zone don't bring down your heating:\r\n\r\n- **Independent zones** - Each zone evaluates and fails separately\r\n- **Graceful degradation** - Failed zones use last-known demand for 1 hour before fail-safe\r\n- **Safe initialization** - No valve actions until all zones have valid temperature readings\r\n- **Clear status reporting** - Controller and zone health visible as entities\r\n- **PID diagnostics** - Per-zone sensors for duty cycle, error, and PID terms\r\n\r\n### Production-Grade Engineering\r\n\r\n- **State persistence** - All control variables survive Home Assistant restarts and crashes\r\n- **90%+ test coverage** - Enforced minimum with 100% target for core control logic\r\n- **Strict type checking** - Full type annotations verified by ty\r\n- **Automated CI** - Every PR runs tests, linting (ruff), formatting, and type checks\r\n- **HACS compliant** - Validated against hassfest and HACS requirements\r\n\r\n## Requirements\r\n\r\n- Home Assistant 2025.10 or newer\r\n- A hydronic underfloor heating system with:\r\n  - Temperature sensor per zone\r\n  - Valve switch per zone\r\n  - (Optional) Boiler heat request switch or summer mode control\r\n  - (Optional) DHW active sensor for residual heat capture\r\n  - (Optional) Outdoor temperature sensor for weather compensation\r\n  - (Optional) Window/door sensors (pauses PID integration, prevents integral windup)\r\n  - (Optional) Supply temperature sensor for heat accounting\r\n\r\n## Installation\r\n\r\n### HACS (Recommended)\r\n\r\n1. Open HACS in Home Assistant\r\n2. Click the three dots menu → **Custom repositories**\r\n3. Add `https://github.com/lnagel/hass-ufh-controller` with category **Integration**\r\n4. Search for \"Underfloor Heating Controller\" and install\r\n5. Restart Home Assistant\r\n\r\n### Manual Installation\r\n\r\n1. Download the latest release from [GitHub](https://github.com/lnagel/hass-ufh-controller/releases)\r\n2. Extract and copy `custom_components/ufh_controller` to your `config/custom_components` directory\r\n3. Restart Home Assistant\r\n\r\n## Quick Start\r\n\r\n1. **Install**: See [Installation](#installation) above\r\n2. **Follow the guide**: The [Quickstart Guide](docs/quickstart.md) walks you through controller setup, adding your first zone, and verifying everything works\r\n\r\n## Operation Modes\r\n\r\n| Mode | Purpose |\r\n|------|---------|\r\n| **Heat** | Normal PID control with zone scheduling |\r\n| **Flush** | All valves open for circulation (no boiler firing) |\r\n| **Cycle** | Diagnostic 8-hour rotation through zones |\r\n| **All On** | Maximum heating - all valves open |\r\n| **All Off** | All valves closed |\r\n| **Off** | Controller inactive |\r\n\r\n## Documentation\r\n\r\n- **[Quickstart Guide](docs/quickstart.md)** - Get up and running with your first zone\r\n- **[Full Documentation](docs/index.md)** - Architecture, algorithms, configuration reference\r\n- **[Control Algorithm](docs/control_algorithm.md)** - PID controller and scheduling details\r\n- **[Fault Isolation](docs/fault_isolation.md)** - How zone failures are handled\r\n- **[Heat Accounting](docs/heat_accounting.md)** - Fair quota allocation with supply temperature weighting\r\n- **[Heating Curve](docs/heating_curve.md)** - Outdoor temperature compensation via heating curve\r\n- **[Configuration](docs/configuration.md)** - All parameters explained\r\n- **[Tasmota Relay Configuration](docs/tasmota.md)** - Setting up Tasmota-controlled relay boards\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flnagel%2Fhass-ufh-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flnagel%2Fhass-ufh-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flnagel%2Fhass-ufh-controller/lists"}