Introduction: Raspberry-Pi Home Heating Controller

Picture of 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 :

Step 1: System Design

Picture of 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

Picture of 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

Picture of 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 "" > && sudo bash

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

Picture of 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 "" > && sudo bash

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 "" > && sudo bash

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

Picture of 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 "" > && sudo bash

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

Picture of 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

Picture of 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 "" > && sudo bash

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.


jonsag (author)2017-12-01

Tweaked some files to run hub and remote on same pi and on stretch.

Great job.


GaryB220 (author)jonsag2017-12-15

Care to share your tweaks jonsag?

aadi1 (author)2017-11-01


Thank you for this beautiful project.

I have encountered a problem when i have tried to install this project

wget "$PI_HEATING_V.tar.gz" -O "/home/pi/pi-heating-remote.tar.gz"

--2017-11-01 07:58:12--

Resolving (,

Connecting to (||:443... connected.

HTTP request sent, awaiting response... 404 Not Found

2017-11-01 07:58:13 ERROR 404: Not Found.

Can you help me with this ?

JffryPwll (author)aadi12017-11-01

Hi Aadi1, This looks like the script could not connect to github. This may have beena temporary network issue. Have you tried again and got the same message ?

ÁgostonD (author)2017-10-12

Best raspberry heating controller I ever see. Is there any chance that you will improve it with more functions? For example local sensor on the hub device?

I have an uneccesary old RPi 1 with a DHT11 sensor, and trying to build a simple controller without remote sensors.

deesexton (author)2017-10-08

Very nice work JffryPwll.
I have a question/request. Is there any way to use this without the separate
Pi sensors? The location of my boiler means that no room is more than 7 metres away. I was wondering if I could connect the sensors in parallel directly to the Controller Hub.
If I used just one Pi Zero for the sensors and paralleled them to it, the optimal place to site it would be next to the boiler (and Hub)!
Many Thanks

lhoskin (author)2017-04-13

I am liking this a lot!
Been looking at a few other similar set-ups but what I like about this one is the remote temperature probes. Something that is a must have for my house.
Need one downstairs and one up stairs with the ability to switch between the downstairs prode during the day and the upstairs one at night.
A couple of thoughts that I have had, the remote probes are communicated with via Wi-Fi, my router occasionally throws a wobbler so I loose the Wi-Fi, would communication via Bluetooth be possible and more reliable?
Also would connecting a touch screen to the hub be a possibility so can be controlled directly?

JffryPwll (author)lhoskin2017-04-16

Hi, I've never used bluetooth, in theory it would work, but would require a lot of recoding. There is functionality to enable schedules when a MAC address is present on the network. So you could switch to an alternative schedule if the hub is unable to connect to a sensor. And yes, you can connect a touch screen, then just open the browser and load http://localhost:8080/status.php full screen, but I just use my tablet to control the hub from my sofa :-)

andyman5002 (author)2017-02-25

You ever considered adding OpenTherm support? I'm in the process of making something similar!

wolffm001 (author)2017-02-07

This is awesome. I'm inspired to build one now. Very neat and complete description :)

I live in Canada and want to build this and then add a few features such as outdoor reset and possibly tie a solar thermal collector. We have in-floor heat so there is a long lag-time between heating demand and supply.

Thanks for posting this...

JffryPwll (author)wolffm0012017-02-07

Thanks wolffm001. What do you mean by 'outdoor reset' ?

wolffm001 (author)JffryPwll2017-02-08

"Outdoor reset is boiler water temperature control scheme that uses outdoor temperature to establish the required temperature of the boiler loop needed to keep the building at the desired temperature. It takes advantage of the relationship that exists between outdoor temperature and building heat loss."

It is basically done by monitoring outside temperature and "anticipating" heating demand inside the building...

wolffm001 (author)wolffm0012017-02-08

JffryPwll (author)wolffm0012017-02-11

After using this for a week or so I estimate my heating can increase internal temperature by +2 deg per hour. So I've created a couple of 'stepped' schedules, #1 start heating at 08:00 if lounge temp < 20deg C, #2 start heating at 07:00 if lounge temp < 18deg C, #3 start heating at 06:00 if lounge temp < 16deg C etc.

wolffm001 (author)JffryPwll2017-02-11

That is cool :) One thing to keep in mind that your room temperature rise is dependent on the outside temperature due to BTU loss/gain through the outside walls. If it is warm outside, and your heating element BTU output is constant, your room temperature will rise faster. If it is cold outside, it will be slower.

Reading the outside temperature gives you the information you need to get much more accurate modeling... the outdoor reset basically reduces water temperature (and therefore BTU transfer) when it is warmer outside and increases it when it cools off outside. When set properly, the outdoor reset matches the BTU output of the heating element to the BTU loss/gain of the outside wall.

If the wall is towards the South, the thermal gain can be significant during the day. You could have a temperature sensor in the wall close to the outside, or you could also sense sunlight...

wolffm001 (author)wolffm0012017-02-11

Here in Canada, we have huge swings in outside temperature in the spring and fall, so outdoor reset is used a lot. We can go from -10 at night to +20 during the day during those times. Without outdoor reset, the heating system overshoots set-points often, especially with a long lag time such as in a concrete floor heated with warm water lines.

JffryPwll (author)wolffm0012017-02-11

Hi wolffm001,

I've got one sensor measuring external temperature in my garden,

and a schedule that starts heating my hot water tank at 06:00 if the external temperature is below 3deg C ( pre-heating the hot water reservoir before heating the house )

My heating system consists of a hot water reservoir which is heated by a gas boiler, and a central heating system which pumps water through the reservoir and circulates this hot water through wall radiators in each room.

Your heating system sounds a bit more complicated, but I'm sure it can be controlled using my app, if you want to have a go at building it, let me know and I'll support you the best I can.

JimM38 (author)2017-02-03

Which sensor? Is your system working at all?

JffryPwll (author)JimM382017-02-03

Hi jim. Which step are you referring to ?

JimM38 (author)JffryPwll2017-02-03

Hi, that was for Swansong who said their sensor is busted. I must have clicked the wrong reply button. Have a good evening.

Swansong (author)2017-01-30

That's a neat setup :) I wish we had something like this because I'm pretty sure the sensor in ours is busted.

About This Instructable




More by JffryPwll:Raspberry-Pi Home Heating Controller
Add instructable to: