https://github.com/lnagel/hass-ufh-controller
Home Assistant Underfloor Heating Controller
https://github.com/lnagel/hass-ufh-controller
hacs hacs-integration heating-control home-assistant home-automation hvac pid-controller python smart-home thermostat underfloor-heating
Last synced: about 2 months ago
JSON representation
Home Assistant Underfloor Heating Controller
- Host: GitHub
- URL: https://github.com/lnagel/hass-ufh-controller
- Owner: lnagel
- License: mit
- Created: 2026-01-05T12:50:19.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-02-07T19:30:04.000Z (about 2 months ago)
- Last Synced: 2026-02-08T04:10:22.196Z (about 2 months ago)
- Topics: hacs, hacs-integration, heating-control, home-assistant, home-automation, hvac, pid-controller, python, smart-home, thermostat, underfloor-heating
- Language: Python
- Homepage:
- Size: 1.14 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Underfloor Heating Controller
[](https://github.com/lnagel/hass-ufh-controller/releases)
[](LICENSE)
[](https://hacs.xyz/)
[](https://github.com/lnagel/hass-ufh-controller/actions)
[](https://codecov.io/gh/lnagel/hass-ufh-controller)
**The only Home Assistant integration designed specifically for hydronic underfloor heating systems.**
While 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.
## Why This Exists
The 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:
| Requirement | Generic Solutions | This Integration |
|-------------|-------------------|------------------|
| **Multi-zone heat aggregation** | Each zone fires boiler independently | Zones coordinate through shared heat request |
| **Boiler/heat pump signaling** | Basic on/off or none | Valve pre-opening, quota-aware requests |
| **EMS-ESP boiler integration** | Manual automations required | Native summer mode, DHW detection |
| **Heat accounting** | Not supported | Supply temperature weighted quota allocation |
| **DHW priority handling** | Not supported | Blocks new heating during DHW, captures residual heat |
| **Weather compensation** | Manual automations or none | Built-in heating curve from outdoor sensor |
| **UFH thermal response** | Adapted from radiator/TRV logic | Native PID tuned for slow thermal mass |
## Key Differentiators
### Purpose-Built for Hydronic UFH
The control algorithm accounts for:
- **Slow thermal response** - PID tuning defaults optimized for concrete screed
- **Valve scheduling** - 2-hour observation periods prevent rapid cycling
- **Minimum run times** - Protects valves from wear while maintaining efficiency
- **Sensor noise filtering** - EMA smoothing handles noisy wireless sensors (Zigbee, etc.)
### Native Boiler Coordination
Multiple zones sharing one heat source need coordination. The controller:
- **Aggregates zone demands** into a single heat request signal
- **Waits for valves to open** before firing the boiler (configurable delay)
- **Manages quota intelligently** - stops requesting heat before a zone's time expires
- **Supports summer mode** - automatically enables/disables the boiler's heating circuit
### Heat Accounting
Multi-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.
- **Supply-temperature normalization** - Quota consumption adjusts to actual supply conditions
- **Single sensor simplicity** - Only needs one manifold supply temperature sensor
- **Automatic fallback** - Works with simple time-based tracking if no sensor configured
See [Heat Accounting](docs/heat_accounting.md) for detailed documentation.
### Weather Compensation
The controller supports outdoor temperature compensation via a configurable heating curve:
- **Heating curve** - Two-point interpolation adjusts supply target based on outdoor conditions
- **Automatic adaptation** - Warmer weather lowers the supply target, reducing energy use
- **Sensor fallback** - Reverts to fixed supply target if outdoor sensor becomes unavailable
See [Heating Curve](docs/heating_curve.md) for detailed documentation.
### EMS-ESP Integration
For users with Bosch, Buderus, Nefit, Junkers, or Worcester boilers running [EMS-ESP](https://github.com/emsesp/EMS-ESP32):
- **Summer mode control** - Disables heating circuit when no zones need heat
- **DHW priority detection** - Blocks new heating cycles during hot water, existing zones continue circulating
- **Residual heat capture** - Flush circuits capture residual heat from the boiler after DHW ends
### Zone Fault Isolation
Sensor failures in one zone don't bring down your heating:
- **Independent zones** - Each zone evaluates and fails separately
- **Graceful degradation** - Failed zones use last-known demand for 1 hour before fail-safe
- **Safe initialization** - No valve actions until all zones have valid temperature readings
- **Clear status reporting** - Controller and zone health visible as entities
- **PID diagnostics** - Per-zone sensors for duty cycle, error, and PID terms
### Production-Grade Engineering
- **State persistence** - All control variables survive Home Assistant restarts and crashes
- **90%+ test coverage** - Enforced minimum with 100% target for core control logic
- **Strict type checking** - Full type annotations verified by ty
- **Automated CI** - Every PR runs tests, linting (ruff), formatting, and type checks
- **HACS compliant** - Validated against hassfest and HACS requirements
## Requirements
- Home Assistant 2025.10 or newer
- A hydronic underfloor heating system with:
- Temperature sensor per zone
- Valve switch per zone
- (Optional) Boiler heat request switch or summer mode control
- (Optional) DHW active sensor for residual heat capture
- (Optional) Outdoor temperature sensor for weather compensation
- (Optional) Window/door sensors (pauses PID integration, prevents integral windup)
- (Optional) Supply temperature sensor for heat accounting
## Installation
### HACS (Recommended)
1. Open HACS in Home Assistant
2. Click the three dots menu → **Custom repositories**
3. Add `https://github.com/lnagel/hass-ufh-controller` with category **Integration**
4. Search for "Underfloor Heating Controller" and install
5. Restart Home Assistant
### Manual Installation
1. Download the latest release from [GitHub](https://github.com/lnagel/hass-ufh-controller/releases)
2. Extract and copy `custom_components/ufh_controller` to your `config/custom_components` directory
3. Restart Home Assistant
## Quick Start
1. **Install**: See [Installation](#installation) above
2. **Follow the guide**: The [Quickstart Guide](docs/quickstart.md) walks you through controller setup, adding your first zone, and verifying everything works
## Operation Modes
| Mode | Purpose |
|------|---------|
| **Heat** | Normal PID control with zone scheduling |
| **Flush** | All valves open for circulation (no boiler firing) |
| **Cycle** | Diagnostic 8-hour rotation through zones |
| **All On** | Maximum heating - all valves open |
| **All Off** | All valves closed |
| **Off** | Controller inactive |
## Documentation
- **[Quickstart Guide](docs/quickstart.md)** - Get up and running with your first zone
- **[Full Documentation](docs/index.md)** - Architecture, algorithms, configuration reference
- **[Control Algorithm](docs/control_algorithm.md)** - PID controller and scheduling details
- **[Fault Isolation](docs/fault_isolation.md)** - How zone failures are handled
- **[Heat Accounting](docs/heat_accounting.md)** - Fair quota allocation with supply temperature weighting
- **[Heating Curve](docs/heating_curve.md)** - Outdoor temperature compensation via heating curve
- **[Configuration](docs/configuration.md)** - All parameters explained
- **[Tasmota Relay Configuration](docs/tasmota.md)** - Setting up Tasmota-controlled relay boards
## License
MIT License - see [LICENSE](LICENSE) for details.