edwardtfn/NSPanel-Easy v2026.11.11

v2026.11.11 - feat: Add PID climate add-ons for slow systems such as underfloor heating

on GitHub

Summary

Two optional climate add-ons that replace the two-point (on/off with hysteresis) control with a PI controller and slow PWM output. They suit slow systems with a high thermal mass, such as water underfloor heating: instead of opening the valve fully until the target is reached and then overshooting while the screed keeps releasing heat, the controller opens it for the share of each PWM cycle that matches the actual heat demand.

This is joint work by @froido (Sven) and me (Peter):

• Sven designed and wrote the PID add-ons in froido/NSPanel-Easy-PID and runs them on his NSPanel EU with underfloor heating. He also added the Heat/Cool fix, the boost chip redraw, the Comfort and Eco presets and the documentation for Advanced Heating Control (AHC).
• Peter merged them into this repository and cleaned them up: the shared base package, adapting them to the current climate base, fixed-rate sampling, keeping the integral term while off and across reboots, the CI builds and the documentation, including the tuning guide.

Each commit keeps its author, so the history shows who did what.

Add-ons

How it works:

• thermostat_embedded stays in place as the user interface and setpoint holder, so the climate page, the climate chip and the Blueprint work as usual. It only switches the dummy relay relay_0.
• Two internal PID controllers (heat and cool) do the actual control. They are defined in a shared nspanel_esphome_addon_climate_pid_base.yaml and regulate on the thermostat's temperature, so they follow the calibration and the thermostat reference.
• The controllers are computed at a fixed rate (pid_sample_interval, default 30 s), independent of how often the temperature sensor reports.
• The integral term is kept while a controller is off and saved to flash every 30 minutes, so the controllers continue from the learned value after switching on again or after a reboot.
• ki is derived from kp and the reset time Tn. The tuning parameters are exposed as entities in Home Assistant, together with diagnostic entities for the output and the integral term of each controller.
• The regulation runs entirely on the panel and keeps working without Home Assistant.
• Combining them with the backup add-on is rejected at build time, as it follows the thermostat's actions, which do not drive the relays here.

Single only:

• The thermostat offers off and heat as "room off/on". The operating mode (heat or cool) comes from pid_mode_entity and is stored in flash. The climate chip and the climate page show the action of the active controller.
• Boost: a switch opens the valve fully for a set time. It has a button on the climate page and, optionally, a chip on the home page (pid_boost_chip) and its remaining time on the climate page (pid_boost_value).
• Presets: Comfort, Eco and Off. The Comfort and Eco temperatures follow Home Assistant entities (pid_comfort_entity, pid_eco_entity), e.g. the helpers of a heating schedule, and are stored in flash. On the climate page, Comfort and Eco are buttons that are highlighted while the setpoint matches their value (pid_preset_buttons).
• Designed for and tested with the Advanced Heating Control Blueprint. The docs include a recommended setup and the status of the AHC features.

Changes

• esphome/nspanel_esphome_addon_climate_pid_base.yaml, ..._pid_single.yaml, ..._pid_dual.yaml: the new packages, plus the matching entry files in the repository root.
• docs/addon_climate.md: new PID mode section covering configuration, entities, boost, presets, AHC and a tuning guide. docs/README.md mentions the PID option.
• .test/esphome_idf_climate_pid_single.yaml, .test/esphome_idf_climate_pid_dual.yaml and .github/workflows/esphome_build.yml: CI builds for both add-ons.

No changes to the Blueprint, the TFT or the existing add-ons, so no minimum versions change.

🤖 Generated with Claude Code

What's Changed

Other Changes

• feat: Add PID climate add-ons for slow systems such as underfloor heating by @meiser79 in #661

Full Changelog: v2026.11.10...v2026.11.11