Raspberry-Pi Home Heating Controller





Introduction: Raspberry-Pi Home Heating Controller

Have you ever wanted to remotely control your home heating and hot water from anywhere, but did not want to pay over £200 for a commercial system ?

Using off-the-shelf hardware and shareware code, you can build your own DIY controller for less than £50.

** Warning this project involves working with mains voltage - please seek help if you are unsure **

All code for this project is available here : https://github.com/JeffreyPowell/pi-config

Step 1: System Design

The system consists of a controller unit ( pi-heating-hub ) which sits next to your central heating and water boiler, and one or more temperature sensors ( pi-heating-sensor-01 , 02 , ... ) which are positioned around your home.

The pi-heating-hub consists of a raspberry pi zero connected to some relays - you will need to refer to your heating system manual to see if it is possible to splice in to your central heating and/or hot water circuits. I was able you connect to both circuits, but you may only be able to connect to the central heating circuit, in which case you will only need one relay connected to the pi zero.

The pi-heating-sensor consists of a pi zero connected to some 1-wire temperature sensors. You can connect as many pi-heating-sensor as required, one for each room you want to monitor ( lounge, bedroom1, conservatory, ... ) and each pi zero can have as many 1-wire temperature sensors connected as you require ( you could have a pi zero in your lounge with three 1-wire temperature sensors measuring : air temperature, one measuring the temperature of the radiator and one hanging out of the window measuring the outside temperature ).

The pi-heating-hub and pi-heating-sensors communicate via your home wifi.

Step 2: What You Will Need

The pi-heating-hub :

  • Raspberry Pi Zero + SD card
  • Power supply
  • USB wifi dongle + micro usb adaptor
  • 1 or 2 channel relay module ( 250 Vac - 10 A )
  • 10 pin GPIO connector ( 2 x 5 pin )

For each pi-heating-sensor :

  • Raspberry Pi Zero + SD card
  • Power supply
  • USB wifi dongle + micro usb adaptor
  • a 4.7kΩ resistor
  • 1 or more 1-Wire Digital Thermometers ( DS18B20 )
  • 10 pin GPIO connector ( 2 x 5 pin )

Step 3: Base Setup of Each Pi Zero

Common Hardware configuration :

First solder the GPIO connectors to the GPIO port pins 1 to 10 on all pi zeros you are going to use.

the pi-heating-hub only uses pins 1, 6, 8 and/or 10, and the pi-heating-sensor only uses pins 1, 6 and 7, the other pins are used just to add physical strength.

Common Software configuration :

We need to configure all the pi zero systems with some common settings, install some handy packages and configure static IPs and hostnames.

First install a clean copy of Raspian Jessie onto the SD card and connect power to the Pi.
( you will need a USB hub to connect a keyboard, mouse and wifi dongle to your Pi zero for the following steps ) Once booted, connect to your Wifi network and open a terminal window.
check for updates,

> sudo apt-get update

Next, from the desktop open the config app [ Pi Menu > Preferences > Raspberry Pi Configuration ]

  • on the System tab, expand the filesystem, change the default pi account password, boot to cli, no auto login
  • on the Interfaces tab, just enable SSH and 1-wire
  • on the Performance tab, reduce GPU memory to 16 - since we will only be using the cli.
  • and on the Localisation tab, set all options to the correct location.

Click Ok to save, but do not reboot yet.

Next we need to give each pi zero a static IP address and new hostname.

Check your network hub DHCP settings. I was able to reserve the following static IP addresses :

  • : pi-heating-hub ( Pi with relays, connected to water heater and/or heating pump )
  • : pi-heating-remote-01 ( Pi with 1-wire thermometers in lounge )
  • : pi-heating-remote-02 ( Pi with 1-wire thermometers in bedroom1 )
  • : pi-heating-remote-03 ( Pi with 1-wire thermometers in conservatory )

To simplify the set-up process I've written a script to do this for us, run this script on each pi zero to configure the static IPs, you should leave the gateway and DNS settings as default.

> curl "https://raw.githubusercontent.com/JeffreyPowell/pi-config/master/base-install.sh" > base-install.sh && sudo bash base-install.sh

Once this is complete you should shutdown,

> sudo shutdown -h now

and disconnect your keyboard, mouse and monitor before powering on again, and you should now be able to connect over SSH using the new static IP and new password.

> ssh pi@

Step 4: Build and Configure the Controller Hub

Hardware :

Connect the relay to the pi zero using the following pins :

Pin 2 - GPIO 5.0V
Pin 6 - GPIO GND
Pin 8 - GPIO 14 ( connected to hot water pump relay - if available )
Pin 10 - GPIO 15 ( connected to Heating relay )

Wire the 2 channel relay as shown in the diagram. ( if you just have a 1 channel relay you only need to wire pin 10 )

Now you'll need to refer to your heating system manual / wiring diagram.

My system currently uses a 15min / 24hr electro mechanical clock and a remote wired thermostat.

The heating is controlled by the timer and thermostat, the hot water boiler constantly on and water temperature is controlled via the boiler water thermostat.

Warning, mains voltage !

I was able to splice the heating relay into the circuit inline with the timer and thermostat.

Now when you turn your old thermostat to maximum, and set your clock to constant on, the heating relay will control your heating pump.

and spliced the hot water relay inline with the boiler water thermostat.

( as a fail back option you could set the heater relay to constant on, and use your old timer and thermostat again )

Software :

After the basic install we need to install the packages and software that will switch the relays and control your heating ( apache, php and mysql )

Connect to the pi over SSH

> ssh pi@

and execute this script to install everything

> curl "https://raw.githubusercontent.com/JeffreyPowell/pi-config/master/pi-heating-hub-install.sh" > pi-heating-hub-install.sh && sudo bash pi-heating-hub-install.sh

As part of the MySQL instal process it will ask for a root password, make a note of this for the next step.

Now we need to configure the database :

> curl "https://raw.githubusercontent.com/JeffreyPowell/pi-config/master/pi-heating-hub-mysql-setup.sh" > pi-heating-hub-mysql-setup.sh && sudo bash pi-heating-hub-mysql-setup.sh

once everything is installed, you can browse to :

and you should see the status page displayed. - we have not set up any sensors yet, so there will be no data.

Step 5: Build and Configure a Temperature Sensor

For each pi zero sensor you want to use, follow the following step

Hardware :

We only need to connect to pins 1, 6 and 7, the other pins are used just to add physical strength.

Pin 1 - GPIO 3.3V ( 1-wire power )
Pin 6 - GPIO GND ( 1-wire ground )
Pin 7 - GPIO 4 ( 1-wire data )

Connect the 1-Wire Digital Thermometer as shown in the diagram. You could connect directly to the pins, or use a small prototype board to connect several 1-Wire Digital Thermometers to the same Pi zero. ( I have two connected to my pi-heating-sensor-01 and three connected to pi-heating-sensor-02 )

Software :

Connect to each pi-heating-sensor in turn,

> ssh pi@

We can now start to install the packages and software that will read the 1-wire thermometer data and make it available the the heating controller hub.

again there is a script to do this :

> curl "https://raw.githubusercontent.com/JeffreyPowell/pi-config/master/pi-heating-remote-install.sh" > pi-heating-remote-install.sh && sudo bash pi-heating-remote-install.sh

once everything is installed, reboot :

> sudo shutdown -r now

now we need to edit the config file ~/pi-heating-remote/configs/sensors

but first we need the discover the serial numbers of the connected 1-wire thermometers

> ll /sys/bus/w1/devices/

Will show that I have two 1-wire thermometers connected, 28-0000056e625e and 28-0000056ead51.

drwxr-xr-x 2 root root 0 Jan 25 15:23 .

drwxr-xr-x 4 root root 0 Jan 24 16:17 ..

lrwxrwxrwx 1 root root 0 Jan 24 16:43 28-0000056e625e -> ../../../devices/w1_bus_master1/28-0000056e625e

lrwxrwxrwx 1 root root 0 Jan 24 16:43 28-0000056ead51 -> ../../../devices/w1_bus_master1/28-0000056ead51

lrwxrwxrwx 1 root root 0 Jan 25 15:23 w1_bus_master1 -> ../../../devices/w1_bus_master1

Now edit the config file and insert these serial numbers.

> vi home/pi/pi-heating-remote/configs/sensors

Delete the default settings and insert the serial number and a name for each 1-wire thermometer.

remove all this :

28-000005cf873e = External

28-000005d0065c = Conservatory

28-000005d01a5a = Conservatory Rad

and add your data, e.g. :

28-0000056e625e = Lounge

28-0000056ead51 = Garden

save and close the config file.

That's it :) everything should now be installed and configured, but lets test it to make sure.

First we can run some tests via our SSH session and verify how many 1-wire thermometers are connected :

> curl localhost:8080/count.php && echo


then we can display the names and values of each thermometer :

> curl localhost:8080/name.php?id=1 && echo


> curl localhost:8080/value.php?id=1 && echo


> curl localhost:8080/name.php?id=2 && echo


> curl localhost:8080/value.php?id=2 && echo


as you can see by the temperatures returned, I need to swap the physical location of the sensors !

We can also test from our desktop via a browser using the following URLs with your static IP :

Repeat the above instructions for all additional sensors, pi-heating-remote-02, pi-heating-remote-03 etc.

Step 6: Configure Input Sensors and Output Devices

Now we have the hub and sensors setup we can start to connect then.

First we will configure the input sensors. ( thermometers )

Browse to the hub status page :


Click on 'Input Sensors' button then click on the 'Scan for new sensors' button.

the app will scan your local network for any thermometer sensors you have set up.

The hub updates sensor data and switches the relays every minute.

Click 'Done' to go back to the main status page.

Next we will configure the output devices. ( relays )

Click on 'Output devices' then click on the 'Add new' button, then click 'Edit' next to the new device.

Update the name to 'Heating' and enter the pin number of the heating relay ( in our case 10 ), the relays I used are active when the GPIO pin is low, so I entered zero in the Pin Active H/L field. ( if your relays are active high, enter 1 )

Click 'Save' then 'Done', then 'Done' again to get back to the status page. ( repeat the last few steps if you have a second relay for the water boiler on pin 8 )

Now we need to create a schedule to switch the heating relay(s) on and off.

Step 7: Create a Heating Schedule

A schedule can be triggered at a specific time, a day of the week, a mode, a timer, when a device is connected to the local network or a combination of these triggers.

A mode is a simple flag that can be either on or off, e.g. 'Working from Home', 'Weekend Away' etc.

A timer is similar to a mode but once activated will automatically deactivate after a specific time, e.g. 'Heating Boost'

A connected device can be anything on the local network identified by its MAC address, 'Jeff's iPhone' etc.

  • To create a Mode, from the status page, click on 'Modes' > 'Add new' > 'Edit' , rename it 'Weekend Away', click 'Save' > 'Done' and 'Done' again to take you back to the status page. The 'Weekend Away' mode button is now displayed on the right of the status page.
  • To create a timer, from the status page, click 'Timers' > 'Add new' > 'Edit', rename it 'Heating boost' and change the duration to '60', click 'Save' > 'Done' and 'Done' again to take you back to the status page. The 'Heating Boost' timer button is now displayed on the right of the status page.

You can click the mode button on and off, and the timer button will count down every minute.

Ok, now we can configure some schedules.

  • From the status page click 'Schedules' > 'Add new' > 'Edit', rename the schedule, set the time and day of week for the schedule to run, select which output device you want to trigger 'Heating' and/or 'Water Boiler', then select the temperature required, ie. when the lounge is below 21 degrees. All these setting need to be TRUE for the schedule to trigger, all other options are set to 'be ignored'. click 'Save' > 'Done' > 'Done'

That's it, your heating is now controlled by your raspberry pi.

Step 8: External Access From the Internet

If you want to control your heating from anywhere you will need to configure your router to forward port 8080 network traffic to the heating controller hub ( )

and for security, add some basic password protected access.

> curl "https://raw.githubusercontent.com/JeffreyPowell/pi-config/master/pi-heating-hub-secure.sh" > pi-heating-hub-secure.sh && sudo bash pi-heating-hub-secure.sh

enter a password when prompted.

The next time you browse to the app you will need to enter username 'admin' and the password you entered.



    • Water Contest

      Water Contest
    • Clocks Contest

      Clocks Contest
    • Creative Misuse Contest

      Creative Misuse Contest

    58 Discussions


    Question 2 days ago


    I have followed your instructions right up to step 4. However when I try to check the status I get the following message.

    Warning: mysqli_connect(): (28000/1045): Access denied for user 'pi'@'localhost' (using password: YES) in /var/www/pi-heating-hub/status.php on line 47

    Connection failed: Access denied for user 'pi'@'localhost' (using password: YES)

    Can you help me.

    Many thanks

    I have set up a Raspberry Pi model B Rev2 with the Raspberry-Pi Home Heating Controller software. The installation was straightforward, thanks to your excellent instructions and I have been able to log on via 8080.
    However I have a major problem! Once I have the Raspberry Pi running with the Home Heating Controller software running, it seems to grab all my bandwidth & I am unable to access anything on the internet.
    When I check my broadband speed (normally 32-38Mb/s), this has almost disappeared.
    I have turned off both Antivirus & Firewall software but this has made no difference.
    If I shut down the Home Heating Controller, all returns to normal with my broadband & internet access.
    Can you suggest what may be causing this problem? If you need any screenshots or further information, please let me know.
    Many thanks in anticipation of your reply

    Hi all,

    I am absolutely engrossed by this project, and I am driving my wife mad!

    This project is what I have been looking for, I just need a bit of help expanding this project as i have four heating zones, hot water, two different types of boiler, solar panel and a heat recuperation device for the stale humid air extracted from the house to the fresh air extracted in.

    I want to be able to use both ,1-Wire Digital Thermometers ( DS18B20 ) and dht11 sensors, the dht11 sensors detect humidity as well as temperature, I have found loads of info about these sensors but have no idea how to put into practice with this project, I have one pi set up as hub/remote already

    (it is attached to the hot water cylinder) and I will soon be adding more pi's , some with the dht11, What I need to know is how the remote needs to display the information so that the hub can find it, and then how the hub will display that information, and control the different parts?

    Any help and links will be greatly appreciated

    Kind regards Paul

    Hello, is it possible to connect and read the temperature sensors connected directly to the hub itself?

    I will be reading the temperature of the hot water tank using the hub and a sensor. The boiler itself doesn't utilise a thermostat on the tank.

    I would also incorporate a sensor for the room temperature in the adjacent room (drill sensor 0.5ft through the wall) for triggering the heating pump. It would be unnecessary to have a separate pi to perform these tasks if the hub can do it.

    1 more answer

    I've followed all the steps in this Instructable, but when I try to input sensors, I continually get these errors:

    [Mon Apr 09 23:33:20.236603 2018] [:error] [pid 1100] [client] PHP Notice: Undefined offset: 4 in /var/www/pi-heating-hub/sensors-list.php on line 65, referer:
    [Mon Apr 09 23:33:20.236837 2018] [:error] [pid 1100] [client] PHP Notice: Undefined offset: 4 in /var/www/pi-heating-hub/sensors-list.php on line 66, referer:
    WARNING: No targets were specified, so 0 hosts scanned.

    I have one remote sensor at, and running the scripts on this are OK.

    I set my network to the correct subnet, and I ran the scripts on my second pi, but I still could not get the sensor to be detected by the hub. (the sensor is detected by the remote pi)

    3 replies


    Edit file : /var/www/pi-heating-hub/sensor-list.php

    change this line to match your subnet :

    $subnet_cidr = '';


    Also, I've just realised, when I set up a pin, it gets set to always on somehow and I can't turn it off?

    Or to

    $subnet_cidr = pathinfo($_SERVER['SERVER_ADDR'], PATHINFO_FILENAME) . ".0/24";

    to make it more dynamic
    (works on my rpi with stretch)

    Well, with Jeff's help I have it working. What an amazing project that is. This is going to save me hours of checking my underfloor heating controls. What great support I have received also. Thanks very much, great job and great help.

    fixed relay proble, connected to 3v, it works ike that, I don't see the charts, i see rrd image, can you help on this one?

    4 replies

    I also had this problem with my version of rrd:
    Look for the line in status.php that has
    "-y 1:5",
    in it, and comment it out.
    Do this also in sensors-list.php

    Hi, did not help I have on Rapsberry PI 3 same rrd version and it;s working. Commented the lines did not help. Any idea?
    Thanks Razvan

    Please attach a screenshot of the problems.
    Also check the apache logs and see if you can get any hints there

    Hi Razvan,

    How is your build configured ?

    What do you mean by 'relay probe' ? what was the problem, and what did you do to fix it ?


    If you can not find the senzor, just add it manually in the code $device_ip2='Ip'; and change all device_ip to device_ip2

    Hi, I have a Rapsberry Pi zero WH, I made this project on Rapsberry 3 with other wiring added some resitors and so on, but now I just follewed this guide, to the temp senzor I have a module so i just connect it, work fine. The relay openens when heating should be on, but never closes, I can do it manually with a python script, what is wrong? Can someone please help?

    This looks really cool and it will be ideal for me to use to monitor the flow and return from my underfloor heating circuits, I have got the 2 Pi's running a hub and a remote. One the remote via the webpage I can see the sensor is reading. and I can access the Hub, but I cant get the hub to grab the sensor reading. My hub has an IP of and my remote has, I have added the MAC address of the remote in the hub, but the status is red and no sensors display.

    Any help please?

    Thanks Paul.

    1 reply

    Forgot to say, Cant find the VAR directory

    Pi Hub.PNGPI Remote.PNG