Hybrid Heating Pump Control – Smart Plug-In Pump Control for Oil Central Heating with return temperature boosting

Smart plug-in pump control for hybrid central heating systems (oil boiler + buffer backed return temperature boosting). Reduces oil consumption by intelligently managing heating cycles, thermal sterilization, and buffer utilization. Built for Shelly 2PM + Addon.

The Problem

Standard legacy oil heaters are "blind." They start burning oil as soon as a pump is needed, even if a solar-heated buffer is already at 100% capacity. They also lack modern legionella protection (thermal sterilization) for hot water reservoirs.

The Solution

This script turns a Shelly Plus 2PM with Addon (and additional relays) into a smart controller that:

• Prioritizes the Buffer: Only burns oil if the buffer is too cold to provide heat.

• Weighted Averages: Uses a Weighted Moving Average (WMA) to filter out sensor noise and prevent nervous pump switching.

• Legionella Guard: Persistently tracks thermal sterilization via Script.storage to ensure water hits 60°C once a week.

• Fail-Safe Hardware: Relays are wired in Normally Closed (NC) configuration. If the Shelly finishes, fails, loses power, or the script crashes, control automatically reverts to the legacy system. No one gets a cold shower.

How It Works

The plug-in system intercepts the pump control lines of the original central heating control (CHC) using three dummy relays. General heating control is left to the CHC. A Shelly 2PM with Addon decides when and which pump runs based on temperature sensors (boiler, hot water, buffer). In case of power failure or Shelly crash, all relays fall back to NC position – the original CHC takes over immediately. No heating outage possible.

Hardware

• 1x Shelly 2PM
• 1x Shelly Addon
• 5x DS18B20 temperature sensors
• 3x dummy relays (NC)
• Power supply for pumps (if required)

Wiring Diagram

┌──────────────────────────────┐
│ Legacy Central Heating       │
│ Control (CHC)                │
└──────────────┬───────────────┘
               │
               V
┌─────────────────────────────────────────────────────────────────────┐
│ 3x Dummy-Relays                                                     │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐         │
│ │ Relay  1        │ │ Relay  2        │ │ Relay  3        │         │
│ │ NC Switch       │ │ NC Switch       │ │ NC Switch       │         │
│ │ CHC -> HKP      │ │ CHC -> UP       │ │ HKP / UP        │         │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘         │
│          │                   │                   │                  │
│          └───────────────────┼───────────────────┘                  │
│                              │                                      │
│                       ┌──────V──────┐                               │
│                       │ Shelly 2PM  │                               │
│                       │ + Addon     │                               │
│                       │             │                               │
│                       │ Switch 0 ───┼──> Relays 1 + 2               │
│                       │ Switch 1 ───┼──> Relay  3                   │
│                       └─────────────┘                               │
└─────────────────────────────────────────────────────────────────────┘
       │                │              │
       V                V              V
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ HKP-Pump    │ │ UP-Pump     │ │ Power Supply│
│ (Heating)   │ │ (Hot Water) │ │ Pump        │
└─────────────┘ └─────────────┘ └─────────────┘

Relay Logic

Component	Function
Relays 1 + 2	Controlled by Shelly Switch 0. NC = CHC controls both pumps. NO = Shelly controls both pumps.
Relay 3	Controlled by Shelly Switch 1. NC = HKP pump runs. NO = UP pump runs.

Operating States

Switch 0	Switch 1	Relays 1+2	Relay 3	Effect
OFF	irrelevant	NC (CHC → HKP + UP)	irrelevant	Failback: CHC controls both pumps (HKP + UP)
ON	OFF	NO (Shelly → HKP + UP)	NC (Shelly → HKP)	Shelly controls both pumps, HKP runs
ON	ON	NO (Shelly → HKP + UP)	NO (Shelly → UP)	Shelly controls both pumps, UP runs

Safety Concept

• Switch 0 = OFF: CHC has full control over both pumps
• Switch 0 = ON: Shelly takes over both pumps, selects which one via Switch 1
• Power failure or Shelly crash: All relays fall back to NC position → CHC controls HKP + UP

Alternative Wiring (Without Dummy Relays)

For advanced users who want to reduce hardware cost, the script can also run without the three dummy relays. In this configuration:

• Pumps are connected directly to Shelly Switch 0 and Switch 1
• CHC is not in the circuit
• Inputs can be used to read the CHC pump signals

Pros / Cons

	With Dummy Relays (this guide)	Without Relays
Fail-safe	Full – CHC takes over on failure	None – Shelly failure = no heating
Cost	~30–50 € for relays	0 €
Complexity	Higher (wiring, space)	Lower
Best for	Permanent installation, peace of mind	Testing, supervised setups

Minimal Configuration (No Relays)

If you choose this route:

1. Connect HKP pump directly to Shelly Switch 0
2. Connect UP pump directly to Shelly Switch 1
3. Remove the CHC from the circuit entirely

If you still want the CHC to be able to trigger pumps (e.g., for thermostat signals), you can:

• Connect CHC pump outputs to Shelly inputs (e.g., SW inputs on 2PM)
• Read input states via Shelly.getComponentStatus("input", 0).state
• Use these signals as additional logic in the script

Example snippet:

let chcHkpRequest = Shelly.getComponentStatus("input", 0).state; // CHC wants heating
let chcUpRequest = Shelly.getComponentStatus("input", 1).state;  // CHC wants hot water

if (chcHkpRequest && !chcUpRequest) {
  // CHC requests heating – decide if smart control overrides
}

This gives you a hybrid approach: smart logic normally, but CHC requests can still influence decisions.

Temperature Sensors (Shelly Addon)

Sensor	Location
Boiler	Boiler outlet/return
Hot water	Hot water reservoir
Buffer top	Upper third of buffer tank
Buffer center	Middle of buffer tank
Buffer bottom	Lower third of buffer tank

Script

The Shelly script implements:

• Weighted moving averages to filter sensor noise
• Plausibility checks to discard invalid temperature readings
• Legionella sterilization – once per week, hot water is heated to ≥60°C
• Buffer-coupled detection – recognizes when the buffer is hydraulically coupled
• Night mode – reduced heating activity during night hours

Key Constants

const __WEIGHTENEDCONST = {
  factorMostRecent: 0.15,   // weight of latest measurement
  factorSequence: 0.85,     // weight of historical average
  factorPlausible: 1.05,    // plausibility threshold
  delta: 4.0,               // temperature difference threshold
  alarm: 43.0,              // alarm threshold
  min: 48.0,                // minimum hot water temperature
  med: 50.0,                // medium hot water temperature
  steril: 60.0,             // sterilization target
  max: 72.5                 // maximum safe temperature
};

Installation

• Add Shelly 2PM + Addon to your Shelly app
• Connect DS18B20 sensors to Addon and adjoust the __SENSORCONFIG mappings.
• Wire relays according to the diagram above
• Upload the script via Shelly Web UI or Shelly Cloud
• Configure DEBUG and LOG flags as needed
• Set script to start automatically
• Temperature-based notifications can be added in the Shelly Smart Control App

License

This project is licensed under the MIT License – see the LICENSE file for details.

Disclaimer

This software controls heating equipment.

The author assumes no responsibility for any damage, injury, or financial loss resulting from the use of this software. Test thoroughly in a safe environment before putting into production. Ensure proper fail-safe mechanisms (like the described relay logic) are in place.

The described relay logic (failback to original central heating control) is an essential part of the safety concept and must be implemented exactly as shown.

This project is provided as inspiration. It is not a one-size-fits-all solution. Your heating system likely differs in hydraulic design, sensor placement, and control logic. Expect to modify the script to fit your specific setup.

---

The code might look 'busy' and hasn't been refactored for beauty – because it's been controlling my actual home heating for over a year. It's battle-tested in the German winter. Every nested IF prevents a cold shower or a wasted liter of oil.