rWCHCd is the software part of the rWCHC project aimed at implementing a versatile weather-compensated central heating controller. The goal is to provide smart, accurate and optimal temperature control based on outdoor temperature variations, building structure and occupant habits, in order to maximize comfort and reduce power usage (minimize both the impact on the environment and the energy bill). The system is designed to be scalable and remote operable (via internet connection).

This project is composed of two parts: a custom-designed hardware module (documented here) to perform the actual power control on heating appliances, and a software module which is the topic of this page.

This software is typically meant to run on a Raspberry Pi host accompanying the rWCHC hardware module to perform all computations and enhanced logic control, but it can operate on any system that supports basic C-library programming interface. As this piece of software has eventually grown over 10,000 lines of (well documented) code and has become a standalone creation, it is now described separately here.

This project stemmed from my need for a reliable and highly configurable controller after having had a bad experience with a brand-name device.


This project falls under a different licensing scheme than the rest of this website. Please read this section carefully.

  • The hardware part (incl. firmware) of this project is currently all rights reserved.
  • The software part (excl. firmware) of this project is currently all rights reserved.

I am still considering suitable licensing schemes at this time. If you are interested in this project feel free to get in touch.

Design goals

My design goals are simple. The system should be:

  • Safe
  • Reliable
  • Versatile
  • Affordable
  • KISS design

This is reflected in the list of software features.

The system is geared toward a “set and forget” approach, only requiring some attention at initial setup time.


The rWCHCd daemon – written in C and documented inline via doxygen – is the “brain” of the heating controller system. By design, computations are performed in integer arithmetics to reduce the load on the host, to improve scalability, and to facilitate implementation on a scaled-down MCU if that ever becomes desirable.

In fact, while developed to manage the rWCHC hardware module from a Rasberry Pi, this control daemon is designed to be both hardware and platform independent:

  • A hardware abstraction layer allows for easy implementation of new hardware modules as “plugins”
  • The software’s only mandatory dependency is the C library


Presently, the following features are implemented (non-exhaustive list):

  • Weather-compensated operation, with virtually unlimited number of building models:
    • Building temperature behavior modelling via inertia time constant
    • Per-model outdoor temperature source
    • Per-model evaluation of frost or summer conditions
  • Virtually unlimited number of heating circuits with any of the following features:
    • Water-based circuits with radiators are supported
    • Per-circuit, independent target ambient temperature
    • Per-circuit building model assignment
    • Direct heating circuits
    • Mixed heating circuits, with 3-way mixing valve:
      • Support for multiple types of valve control algorithms: bang-bang, successive approximations, PI controller
      • Support for temperature deadzone in all algorithms
      • Support for actuator deadband in all algorithms
    • Support for multiple types of heating curves (linear and bilinear approximations are implemented)
    • Support for ambient temperature modelisation in the absence of an ambient sensor
    • Support for accelerated cooldown and boost warmup transitions
    • Support for water temperature rate of rise control
    • Support for optional circuit ambient temperature sensor
    • Support for optional circuit water return temperature sensor
    • Support for automatic circuit turn-off based on outdoor temperature evolution
    • Support for timed cooldown at turn-off
    • Support for min/max limits on circuit water temperature
  • Virtually unlimited number of DHWT (Domestic Hot Water Tanks) with any of the following features:
    • Support for boiler-integrated tanks
    • Support for automatic switch-over to (optional) integrated electric-heating
    • Support for single and dual sensor operation (top/bottom) with adaptive hysteresis strategies
    • Support for timed feedpump cooldown at untrip with temperature discharge protection
    • Support for 5 charge priority models (no priority, parallel or absolute; with heat request selection)
    • Support for forced manual charge
    • Support for charge duration cap
    • Support for DHW circulator pump
    • Support for min/max limits on DHW temperature
    • Support for maximum intake temperature limit
    • Support for periodic anti-legionella high heat charge
  • Type-agnostic heat source support (currently only boiler type implemented) with any of the following features:
    • Support for consumer shift (e.g. to accelerate warmup after a cold start or to evacuate excess heat)
    • Support for consumer reduction delay signal (signal consumers to delay heat request reduction)
    • Boiler type heat source implements:
      • Automatic frost protection in all operation modes
      • Support for burner minimum continuous on/off time to reduce wear
      • Support for adaptative trip/untrip hysteresis with low and high temperature limits
      • Support for automatic boiler “sleeping” turn-off based on last heat request time
      • Support for several automatic turn-off strategies
      • Support for boiler minimum and maximum temperature (with signalling to consumers)
      • Support for return water minimum temperature (with or without return mixing valve)
      • Support for consummer delay after burner run (to prevent overheating)
  • Support for automatic summer switch-over based on outdoor temperature evolution, with summer maintenance of pumps and valves
  • Support for pump cool down timeout
  • Support for several global operation modes (full off, comfort, eco, frost-free, manual…)
  • Virtually unlimited number of hardware controllers:
    • Hardware-agnostic input/output interface (adding support for new hardware is a simple matter of adding a driver for it)
    • Driver for current prototype hardware supports:
      • Communication over SPI bus
      • Multiple RTD temperature sensors variants (currently Pt1000 and Ni1000)
      • Support for per-sensor fixed temperature offset
      • Support for periodic self-calibration
      • Time accounting of all triac/relay operations (i.e. “on/off since, total on/off time, number of power cycles”, etc)
      • Basic user-hardware interaction:
        • Global operation mode change via tactile switch
        • Display of individual sensor temperature
  • Support for multiple data logging and stats backends, currently:
    • simple CSV files
    • rrdtool databases
  • Support for logging sensor/relay data as well as internal (computed) states and values (e.g. targets, modelized temperatures, etc)
  • Support for basic (weekly) scheduling (setting runmode – comfort, eco, etc – and anti-legionella DHWT charge)
  • Support for ISC-style declarative configuration file format
  • Foundation of a simple D-Bus interface for remote control via a proof of concept web application
  • Foundation of a simple permanent storage interface for state persistence

Provisions in the software have been made to support the following additional features:

  • Support for individual (per circuit/DHWT/heat source) operation mode
  • Circuits:
    • Support for transition timing optimisation (anticipated cooldown, boost warmup timing…)
    • Support for zone valves
  • DHWT:
    • Support for DHWT cascade, with priority
  • Heat sources:
    • Support for virtually unlimited number of heat sources, with cascading and/or switch-over
    • Support for other types of heat sources (e.g. heat pumps or heat exchangers for district heating…)
    • Support for boilers with 2-stage burners
  • Support for solar heating
  • Support for multiple instances (chaining/cascading)
  • Support for full remote control
  • Support for smart scheduling

Also considered:

  • Support for air-based circuits
  • Support for cooling systems
  • Support for presence indicators (e.g. sensors or IFTTT) to learn the occupants habits
  • Support for HomeKit integration

The daemon code is currently unreleased.

Proof-of-concept web application

A basic, proof-of-concept web interface has been developed in Python (relying on framework), it allows for setting various parameters and remote controlling the heating system (turning it off/on, setting heating mode, etc). When using the rrdtool logging backend, a small CGI script is available to display historical graphs of various datapoints, see for instance:

mix-1w mix2-1w bmodel-1w

(The colors are entirely configurable if you don’t share my tastes ;)