--- title: "PID Controller" description: "PID controller in TapHome: the P, I and D terms, output to a valve, thermostat or variable, a relay through a module output in PWM mode and an interactive room simulator." url: "https://taphome.com/en/docs/smart-rules/pid-controller/" language: en lastmod: 2026-11-11 generator: hugo ai: topics: ["smart-rules","pid-controller","pwm","heating-control","temperature-regulation"] questions: ["What does the PID controller do and when should I use it instead of the hysteresis controller?","What do the P, I and D terms mean?","Why does the temperature stay below the setpoint with the PID controller?","Why does the temperature oscillate around the setpoint with the PID controller?","How do I control a boiler relay or electric heating with the PID controller?","What is a module output in PWM mode and what period should I set?","What does the PID controller send to a valve, a thermostat and a variable?","Why is the integral reset after the setpoint changes?","What happened to a PID controller with a switch after the upgrade to 2026.1?","What Kp and Ki should I set for underfloor heating, radiators or a mixing valve?","How do I convert the proportional band and integral time to Kp and Ki?","Why does the room stay below the setpoint for a long time after a window is opened or the rule is edited?","When should I use the Temperature hysteresis controller instead of the PID controller?"] --- # PID Controller Last updated: 2026-11-11 **PID controller** calculates how much power heating (or cooling) needs from the difference between the measured value and the setpoint of the controller — most often the room temperature. It sends the result in percent to a valve, the thermostat of a heating element, a blind or a variable. This page describes the behavior from version 2026.1. **For ordinary room control**, [**Temperature hysteresis controller**](https://taphome.com/en/docs/smart-rules/hysteresis-control/) is enough: it switches a relay on and off around the setpoint and can open a valve smoothly according to the band. It has no integral that could overshoot, and the temperature settles close to the setpoint. Use the PID controller when you need the setpoint exactly and without steady-state error — supply water behind a mixing valve, fast systems, humidity or level. ## Try the PID controller ## P, I and D terms The output is the sum of three terms, which the controller calculates from the deviation from the setpoint at every update. - **The P term** (proportional) is proportional to the deviation: with the default Kp = 10 it gives 10% power for every degree the room is too cold. On its own it is not enough — when the room is almost at the setpoint, it gives almost nothing, and the room stops below the setpoint, where a small deviation gives exactly as much power as the room loses (in the simulator, move the I term to 0). - **The I term** (integral) adds up the deviation over time: with the default Ki = 0.5 it grows by 0.5% for every degree and minute. It grows to the power the room needs permanently and holds it even at zero deviation. An I term that is too large grows faster than the room can respond, and the temperature oscillates (in the simulator, move the I term to 5); while the output is at 100%, the integral keeps growing and causes an overshoot once the setpoint is reached. - **The D term** (derivative) reacts to how fast the deviation changes. It is 0 by default; slow rooms do not need it. ### Standard form: band and integral time Heating controllers from other manufacturers (KNX, Siemens) set the same terms in a different form: - **Proportional band Xp** = 100 / Kp (°C) — the deviation at which the output reaches 100%. Kp 10 is Xp 10 °C. - **Integral time Tn** = Kp / Ki (minutes) — how long it takes the I term to match the P term at a constant deviation. Kp 10 and Ki 0.5 is Tn 20 min. - **Derivative time Tv** = Kd / Kp (minutes). In the app you enter Kp, Ki and Kd; calculate them from the band and the times: Kp = 100 / Xp, Ki = Kp / Tn, Kd = Kp × Tv. ### Recommended values by system The default Kp 10 and Ki 0.5 give rooms a much shorter integral time than KNX controller manufacturers set. In a slow system they therefore overshoot — underfloor heating still oscillates with them after eight hours (in the simulator, the **Floor** system with Kp 10 and Ki 0.5). The presets of most KNX controllers converted to TapHome settings: | System | Xp / Tn | Kp | Ki | PWM period | |---|---|---|---|---| | Underfloor heating (wet system), ceiling or floor cooling | 5 °C / 240 min | 20 | 0.083 | 20 min | | Radiators, zone valve with a thermal actuator | 5 °C / 150 min | 20 | 0.133 | 15 min | | Direct electric heating | 4 °C / 100 min | 25 | 0.25 | 10 min | | Fan coil (0–10 V valve) | 4 °C / 90 min | 25 | 0.278 | — | | Mixing valve (supply water) | 24 °C / 1.5 min | 4.17 | 2.78 | — | The D term is 0 for all of them. A slower I term does not overshoot, but after the integral is reset ([when](https://taphome.com/en/docs/smart-rules/pid-controller/#timing)) the power takes a long time to build up — in the simulator, **Open window** or the P slider during a run. Supply water heats up in minutes, so it needs a much smaller P term and a larger I term (the **Mixing valve** system). Do not switch a thermal actuator with a period shorter than 15 minutes. ## Setting up the PID controller 1. **Controller** — the device with a setpoint: a thermostat, or a humidity, CO2 or level controller. 2. **Heating & Cooling Mode** — fixed, or from the season device; offered only for a temperature controller. A new controller links itself to the season device of the location when the location has one; when the season is off, the outputs get zero power (a thermostat gets the value of zero in the mode's range). 3. **PID controller** — the P, I and D terms (section [P, I and D terms](https://taphome.com/en/docs/smart-rules/pid-controller/#pid)). 4. **Output devices** — tap an output to set its mode (section [Outputs and their mode](https://taphome.com/en/docs/smart-rules/pid-controller/#outputs)). 5. **Advanced settings** — the update rate and the reset threshold are explained in section [When the controller calculates](https://taphome.com/en/docs/smart-rules/pid-controller/#timing). The "**Max accumulated integral**" row limits the I term: at 100% it can give full power on its own; a lower value reduces the overshoot after a long warm-up, but also the power the controller holds at zero deviation. ## Outputs and their mode 1. **Mode** — the range under the option is the part of the controller output that the output processes. 2. **Min / max** — thermostat only: the setpoint at the ends of the mode's range. An output in **Positive** mode gets only heating (when the room is cold), in **Negative** mode only cooling. A new output starts in **Both** mode: from version 2026.1, an analog output or a blind in this mode gets power only in the direction of the season when the season is heating or cooling. With the season set to heating and cooling, and without a season, it gets the magnitude of the correction without its sign, so a two-pipe valve opens when the room is overheated. Therefore switch a valve that only heats to **Positive**; when all outputs of the rule are in this mode, the integral does not go negative either. | Output | What it gets | |---|---| | Analog output, blind | the controller output 0–100% | | Thermostat (setpoint) | linearly within the mode's range: **Positive** from Min (0%) to Max (100%), **Negative** from Max (0%) to Min (100% cooling), **Both** from Min (100% cooling) through the middle (0) to Max (100% heating) | | Variable | the correction in percent without clipping — above 100 and, in **Negative** or **Both** mode, also negative | When the controller has no valid value — the thermostat is in error or has no temperature or setpoint —, it releases the outputs: a smart rule with a lower priority or the device's default value takes over; without them, the output stays at its last value. Once the value returns, the controller controls them again immediately. ## When the controller calculates and when it resets the integral - **Update:** with every new value of the controller the integral is updated, but a new output goes out at most once per minimum time (1 minute by default); without a change of the value, the controller recalculates anyway after the maximum time (10 minutes by default). - **A manual setpoint change** (in the app, on the thermostat) goes out immediately, without waiting for the minimum time. An automatic change — for example from equithermic regulation, which can come often — waits. - **A setpoint change by the threshold** (the "**Reset PID when setpoint changed by:**" row) resets the integral. A new rule gets a threshold of 10% of the thermostat's setpoint range, for example 2 °C for a range of 10–30 °C. A night setback by the threshold therefore starts from the P term, and in the morning the integral builds up from scratch (in the simulator, stop time with ⏸ and lower the setpoint by 2 °C). A threshold of 0 turns the reset off. - **Editing the rule** — every save, even a change of Kp or Ki — resets the integral, and the power builds up again (in the simulator, move the P term during a run). - **Limiting condition:** while it applies, the controller does not calculate and releases the outputs; after it ends, the controller starts again with a zero integral (the **Open window** button in the simulator). - **Long pause:** when more than the maximum time plus 3 minutes passes since the last calculation — a sensor error longer than about 13 minutes, a control unit outage —, the integral is reset. - **An output in manual mode** is invisible to the controller: it keeps calculating, and the integral changes according to the temperature that the manually set valve causes (the **Manual mode 100%** button). A manual override that ends at the next automatic change is ended by the controller's next write; it lasts longer with a time limit or until the user ends it. ## Relay and PWM The relay of a boiler or electric heating cannot set 35% power — it can only switch on. The percentage is therefore converted to time: with a period of 15 minutes and an output of 35%, the relay is on for about 5 minutes and off for 10 minutes. This is what a TapHome Bus module output does in **Pulse-width modulation** mode: 1. In the module settings, switch the digital output with the relay to **Pulse-width modulation** and set the period (600 to 7200 seconds; for your system, see the PWM period column in the [preset table](https://taphome.com/en/docs/smart-rules/pid-controller/#presets)). The option is available on modules that support PWM — [list](https://taphome.com/en/docs/configuration/power-limiting-pwm-groups/#modules). 2. The output thereby becomes an analog output — add it to the PID controller as an output in **Positive** mode. When the output rises in the middle of a period after the relay has already switched off, the module switches it on briefly again in the same period. Add several outputs with a limited shared power to a group — [Power Limiting with PWM Groups](https://taphome.com/en/docs/configuration/power-limiting-pwm-groups/). Relays of other systems (Shelly, Zigbee, Modbus) have no PWM mode; for them, use **Temperature hysteresis controller** with a hysteresis of a few tenths of a degree. ## PID with a switch after the upgrade to 2026.1 The old PID temperature controller (up to version 2025.2) could switch a switch by itself. During the upgrade to 2026.1, its switching outputs move to a new **Temperature hysteresis controller** smart rule named "Migration from - …"; the other outputs stay in the PID controller, and a PID controller that had only switches is removed. After the upgrade, check the converted hysteresis controller: the conversion gives it a heating hysteresis of 0.2 °C (until the fix in 2026.1 it set it to 0, and the relay switched every few seconds). If the relay is on a TapHome Bus module, you can instead switch the output to **Pulse-width modulation** and add it to the PID controller (section [Relay and PWM](https://taphome.com/en/docs/smart-rules/pid-controller/#pwm)); then delete the converted hysteresis controller.