search

roadsnail / Pi-ve

Raspberry Pi Zero W Controls Hive SLR/SLT using Zigbee and Wifi networks- A Standalone Heating/Hot water Control solution without the British Gas Cloud
GNU General Public License v3.0
33 stars 1 forks source link
boiler-controller hive message-broker mqtt node-red pi-ve raspberry-pi slr2 slt2 slt3 thermostat zigbee zigbee2mqtt

readme

Pi-ve

A Raspberry Pi Zero W controls a Hive Active Thermostat (SLTx) /Boiler Controller (SLR2) - A standalone Central Heating (CH)/ Hot Water (HW) control solution (without the British Gas 'Cloud').

Control your Central Heating/Hot Water boiler on your local network using Pi-ve from:-

The Node-RED dashboard Web page offers full control of CH and HW with up to 8 programmable 'On' periods per day plus Override/Boost functions.

In addition, the Pi-ve may be controlled using MQTT commands OR HTTP Requests from an external system (eg. A Home Automation platform or phone/tablet app).

Pi-ve_1

Pi-ve System - SLR2, Zigbee USB Stick (attached to Raspberry Pi Zero W), SLT2

But why go to the trouble of controlling Hive Active from a Pi when it's easy to use the Hive Hub and control heating and hot water from the Hive App?

Well, the main reason I have taken this approach is to remove my dependence on the Hive Cloud and have full local control over my boiler even during Hive system outages, (yes they do happen), and ISP/Internet issues.

The second reason is to remove any dependency my Home Automation system has on Hive's undocumented APIs which may change without notice. I have been caught out twice in the past when British Gas made changes.

Lastly, British Gas may decide at some time to stop supporting Hive Active. If or when that happens, my Hive investment will continue working.

And lastly lastly, I have enjoyed the new challenges of 'coding' in node-RED and hacking together the javascript to enable the web interfaces into Pi-ve.

Contents

  1. What is Pi-ve
  2. Where can I get my very own Pi-ve?
  3. Can I use a Raspberry Pi 3 or 4?
  4. The Pi-ve Dashboard - Set up CH/HW 'On' Timers, 'Boost' and Control your Heating/Hot Water from your Pi-ve
  5. The Pi-ve HTTP Screen - Control Pi-ve with HTTP requests
  6. Control Pi-ve with HTTP GET Request using curl
  7. Control Pi-ve with HTTP request method POST
  8. Control Pi-ve by Publishing to Topics on Pi-ve Mosquitto Message Broker
  9. Software/Firmware Sources
  10. Pi-ve software configuration
  11. Review Progress and Check Software Components
  12. Configure Hive Active SLR/SLT - Factory Reset and Join Pi-ve Zigbee Network
  13. node-RED - Import flow
  14. Pi-ve Dashboard Timed Off/On Slots (in timer (TMR) Mode)
  15. Attributions

What is Pi-ve?

Pi-ve =

Hardware:

Software:

Firmware:

Where can I get my very own Pi-ve?

Disclaimer - WARNING - If you intend to play along with this project, be very aware that the Hive SLR Boiler Controller will require connecting to a mains electricity supply and that the connections to the controller's Central Heating and Hot Water terminals will be switching at mains voltage! Get it wrong, or touch the wrong parts and serious injury or death may result! Also, keep it well away from children and pets whilst developing and testing this. You have been warned. If uncertain how to connect the Boiler Controller (SLR2), then obtain advice/assistance from a qualified person.

If you are confident and happy with the warning above and want to make your own Pi-ve, then here is a list of parts:-

Next - Add about 1 day to download and configure the software

Result - A standalone Heating/Hot Water Controller, lots of fun, and a chance to learn how to configure a Pi, MQTT broker, Node-RED and Koenkk's Zigbee2MQTT software/firmware

Alternatively, buy a Hive Active system and install it, but where's the fun and education in that?

Can I use a Raspberry Pi 3 or 4?

Yes, of course. Model 3 and 4 have onboard Wifi making them very suitable for this project. The reason I chose a model Zero W was it has onboard Wifi allowing me to place it somewhere convenient where it is in good Zigbee network range for the SLR/SLT and Wifi range. I also had one surplus to requirements. In addition, my Pi-ve runs an additional task of listening to my Bluetooth LE thermometers and relaying temperature data to my Home Automation system. But that's another story...

The Pi-ve Dashboard - Set up CH/HW 'On' Timers, 'Boost' and Control your Heating/Hot Water from your Pi-ve

The below screenshot shows the Pi-ve status/control web page created in node-RED and running on the Pi Zero. Just connect to the node-RED dashboard from a browser on your network and browse to URL http://your-pive-ip-address:1880 (inserting your Pi-ve actual IP4 address of course).

It shows the current status of the Pi-ve, online, current time, plus the current temperature/thermostat setting and CH/HW Off/On and 'Demand' states.

2021-05-19 23_21_24-Node-RED Dashboard Example Pi-ve Dashboard screenshot showing Pi-ve 'online', room temperature 19.53 deg C, thermostat setting 20 deg. Hot Water has been boosted with 28:33 minutes remaining. Looking at the CH Time Slots for the current time (23:21) CH is programmed to 'On' with a Thermostat setpoint of 20 deg C, however, 'Override' is active forcing CH Off (indicated by the green 'Override State' LED). The HW 'Demand' icon is active (on - not greyed out), however the CH icon is greyed out thus inactive (off) and red LED state

The Pi-ve HTTP Screen - Control Pi-ve with HTTP requests

A screenshot showing Off/On, Manual/Timer Mode and Boost buttons on a simple browser screen that allows for easy control from a smartphone/tablet by pointing your browser to http://your-pive-ip-address:1880/ctrl/page

Pi-ve-HTTP

Example of /ctrl/page showing Pi-ve room temperature 18.94 deg C, thermostat setpoint 20 deg C. Both Heating and Water demand is 'On' and SLR2 outputs set to demand 'heat' from the attached boiler. 'Timer' is active for water, while 'Boost' is active for a further 59:04 minutes for heating.

This allows basic control of the Pi-ve without the 'Time Slot' editing functions provided by the Node-RED Dashboard screen. Although not offering Time Slot editing functions, it is better optimised for small screen devices.

Control Pi-ve with HTTP GET Request using curl

Basic control of Pi-ve from a simple HTTP GET request command:-

Thermostat setpoint

Central Heating

Hot Water

Control Pi-ve with HTTP request method POST

Pi-ve may be controlled using HTTP JSON formatted requests:-

POST HTTP://your-pive-ip-address:1880/cmd with Content-Type: application/json

List of valid payloads below (in and including the curly brackets). eg. To switch the HW output to off, POST json {"HW":"Off"}

Thermostat setpoint

Central Heating

Hot Water

Control Pi-ve by Publishing to Topics on Pi-ve Mosquitto Message Broker

In addition to the above control methods, Pi-ve may be controlled by publishing control payloads to Topics on Pi-ve's Mosquitto Message Broker:-

List of valid payloads below. eg. To set the Thermostat setpoint to 22.5 deg C, publish to the MQTT message broker at host Pi-ve, topic pive2mqtt/SLRCtrl/savedSP payload 22.5

Thermostat setpoint

Central Heating

Central Heating

Software/Firmware Sources

Your Pi-ve will require the following software/firmware. Here is a list of software sources and brief instructions for installing the necessary software. I suggest installing and configuring the software in the order below, ensuring that things work properly at each stage of your build.

Some guidance on software configuration is included in the next section (below).

Firmware

Other Zigbee USB solutions may be used for this project. I just happened to have a CC2531 surplus to requirements as I have upgraded my main Zigbee network controller to a TI CC2652R based module. In my experience, the CC2531 is great at controlling just a few Zigbee devices but struggles with larger Zigbee networks. In this application, the CC2531 copes easily with just two Zigbee connections (the Hive SLR and SLT).

Software

Raspberry Pi OS

https://www.raspberrypi.org/software/operating-systems/ . There are plenty of guides explaining how to install Raspberry Pi OS onto the Pi Zero W so that you may connect in 'headless' mode.

Following the installation of the OS, connect to your Pi and run raspi-config (sudo raspi-config) and:-

  1. Set a new password for user Pi (mandatory)
  2. Set a Hostname for your Pi. I suggest Pive.
  3. Expand Filesystem (optional)

Mosquitto MQTT Message Broker for Raspberry Pi

Mosquitto and clients can be installed from the Pi OS repository. In essence, login to your Pi as user Pi, then...

sudo apt update
sudo apt upgrade
sudo apt-get install mosquitto mosquitto-clients

Node-RED

See the official install guide here https://nodered.org/docs/getting-started/raspberrypi . Login as user Pi and in the home directory run the command given on the guide page. This will take some time on the Raspberry Pi Zero.

Zigbee2mqtt (V1.19.1)

Follow the Official installation guide at https://www.zigbee2mqtt.io/getting_started/running_zigbee2mqtt.html AFTER reading the next two tips:-

Installation of Zigbee2mqtt will take a few minutes, with many warnings thrown up. Don't panic, these may be ignored.

Zigbee2MQTT software should start correctly after following the official installation guide, however in addition to the configuration settings (in the official guide), please take note of the additional configuration notes in the Zigbee2MQTT software configuration section below. including instructions on how to revert the latest version (installed above) to the tested version (v1.19.1).

Pi-ve software configuration

Create Mosquitto Configuration file located at /etc/mosquitto/mosquitto.conf, suggested contents

# Place your local configuration in /etc/mosquitto/conf.d/
#
# A full description of the configuration file is at
# /usr/share/doc/mosquitto/examples/mosquitto.conf.example

pid_file /var/run/mosquitto.pid

persistence true
persistence_location /var/lib/mosquitto/

log_dest file /var/log/mosquitto/mosquitto.log

include_dir /etc/mosquitto/conf.d

Following installation, set the SYSTEMD to start node-RED at startup thus:

pi@pive:~ $ sudo systemctl enable nodered
Created symlink /etc/systemd/system/multi-user.target.wants/nodered.service → /lib/systemd/system/nodered.service.
pi@pive:~ $
pi@pive:~ $ sudo systemctl start nodered

Reboot your Pi-ve and ensure node-RED is started by pointing a browser at http://your-pive-ip-address:1880 and ensure node-RED responds with an empty flow screen.

Next, install some additional node-RED nodes required by the Pi-ve flow (when we install it later).

These may be installed at the node-RED flow creation screen by selecting 'MENU' - Manage palette

Select the 'Install' tab.

For each of the nodes listed below, enter the name into the 'search' field, then when the node is found and displayed, click 'install'

List of additional nodes:-

node-red-dashboard
node-red-node-ui-list
node-red-contrib-ui-led
node-red-contrib-ui-media
node-red-contrib-simple-gate
node-red-contrib-moment

Lastly, install some icon graphics used by the node-RED dashboard to indicate the SLR online and CH/HW demand status.

Copy file Pive-images.tar.gz from the repository into user Pi home directory

Then enter the following tar command to unzip the images into node-RED.

pi@pive:~ $ tar -xzvf  Pive-images.tar.gz
./.node-red/lib/ui-media/lib/Images/
./.node-red/lib/ui-media/lib/Images/slr2-online.png
./.node-red/lib/ui-media/lib/Images/manActiveHW.png
./.node-red/lib/ui-media/lib/Images/HW_On.png
./.node-red/lib/ui-media/lib/Images/slr2-offline.png
./.node-red/lib/ui-media/lib/Images/tmrActiveCH.png
./.node-red/lib/ui-media/lib/Images/HW_Off.png
./.node-red/lib/ui-media/lib/Images/tmrActiveHW.png
./.node-red/lib/ui-media/lib/Images/CH_On.png
./.node-red/lib/ui-media/lib/Images/manActiveCH.png
./.node-red/lib/ui-media/lib/Images/CH_Off.png

If you have successfully followed the official Zigbee2MQTT installation notes earlier, your Pi-ve should have started Zigbee and made a connection to the Mosquitto Message broker running on the Pi.

The Pi-ve node-RED flows have been tested on version 1.19.1 of zigbee2mqtt which is a slightly older version currently (26th Aug 2021) available from the github repository and it is highly recommended that you should git reset your installation to that version. This will only take a few minutes.

So run the following commands to stop zigbee2mqtt (just in case it is running), git reset to the version 1.19.1 commit hash, install dependencies then restart zigbee2mqtt....

cd /opt/zigbee2mqtt
sudo systemctl stop zigbee2mqtt

# Revert to version 1.19.1
git reset --hard 9bd46932c365e886ed0b1f9b8740d8cce632230c

# Install dependencies (as user "pi")
# This will take a few minutes, ignore warnings
npm ci

sudo systemctl start zigbee2mqtt

Zigbee2MQTT Configuration - Additional Steps

Make the following additions to the Zigbee2MQTT configuration.yaml file to:-

Documentation for the web-based frontend may be found here

After making any changes, either reboot your Pi or restart zigbee2mqtt 

sudo systemctl restart zigbee2mqtt

Example configuration.yaml

homeassistant: false
permit_join: true
mqtt:
  base_topic: pive2mqtt
  server: 'mqtt://localhost'
serial:
  port: /dev/ttyACM0
frontend:
  port: 7070
  host: 0.0.0.0
advanced:
  log_level: error
  last_seen: epoch

Review Progress and Check Software Components

Progress Review

So far, the Pi-ve software has been installed and hopefully configured correctly and all software components are working.

If the configuration has got this far, then node-RED must be installed and working, as it is possible to connect to it with a browser connected to the Pi-ve IP address at port 1880

It may be useful at this point to check that the Mosquitto Message Broker is also functioning correctly and that Zigbee2MQTT is running, can connect to the Message Broker, and it can at least connect to a functioning Zigbee co-ordinator (the CC2531).

Mosquitto Message Broker Status

Check the status of the Message Broker service:

pi@pive:~ $ sudo systemctl status mosquitto
● mosquitto.service - Mosquitto MQTT v3.1/v3.1.1 Broker
   Loaded: loaded (/lib/systemd/system/mosquitto.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2021-04-30 12:59:25 BST; 1h 11min ago
     Docs: man:mosquitto.conf(5)
           man:mosquitto(8)
 Main PID: 366 (mosquitto)
    Tasks: 1 (limit: 877)
   CGroup: /system.slice/mosquitto.service
           └─366 /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf

Apr 30 12:59:24 pive systemd[1]: Starting Mosquitto MQTT v3.1/v3.1.1 Broker...
Apr 30 12:59:25 pive systemd[1]: Started Mosquitto MQTT v3.1/v3.1.1 Broker.
pi@pive:~ $

The command sudo systemctl status mosquitto should return something similar to the above. If not, then the prime suspect will almost certainly be a problem with options in the Mosquitto configuration file located at /etc/mosquitto/mosquitto.conf

An extremely useful and highly recommended tool for checking Mosquitto is MQTT Explorer from Thomas Nordquist and is available for all major software platforms - Link

The Zigbee2MQTT Service Status

Similarly, check the Zigbee2MQTT service status:

pi@pive:~ $ sudo systemctl status zigbee2mqtt
● zigbee2mqtt.service - zigbee2mqtt
   Loaded: loaded (/etc/systemd/system/zigbee2mqtt.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2021-04-30 13:15:34 BST; 54min ago
 Main PID: 654 (node)
    Tasks: 23 (limit: 877)
   CGroup: /system.slice/zigbee2mqtt.service
           ├─654 npm
           ├─668 sh -c node index.js
           └─669 node index.js

Apr 30 13:15:34 pive systemd[1]: Started zigbee2mqtt.
pi@pive:~ $

The command sudo systemctl status zigbee2mqtt should return something similar to the above. If not, then check logs (syslog) just after stopping ( $ sudo systemctl stop zigbee2mqtt) then starting ( $ sudo systemctl start zigbee2mqtt)

The logs should give a clue as to what is stopping the service from coming up cleanly.

Useful information can be found at the official Zigbee2MQTT documentation site here

The usual suspects are:

Configure Hive Active SLR/SLT - Factory Reset and Join Pi-ve Zigbee Network

The Hive Active Thermostat (SLT) and Boiler Controller (SLR) can now be connected to the CC2531 Zigbee co-ordinator to form a 3 node Zigbee network.

To allow the SLR/SLT devices to join the network, (Zigbee) 'Join' must be enabled on the Pi.

From a webbrowser, go to http://pi-ve-ip-address:7070 to access the Zigbee2MQTT frontend. If this fails, then review the section configuring Zigbee2MQTT above ensuring that the frontend: section in configuration.yaml has been set up.

Web-frontend-zigbee2mqtt Web frontend Zigbee2MQTT screenshot - showing 'Join' button, the SLR/SLT devices and friendly names

Click on the 'join' button on the right-hand side of the menu bar to display 'Permit join'. This should allow new Zigbee devices to join the network.

Next, the SLR/SLT should both be factory reset and placed into pairing mode. Here is an overview of the process, a detailed description of pairing is below.

Stage 1. Firstly, the SLR will be reset and paired, we should observe log messages appearing on the zigbee2MQTT web frontend screen as it pairs with the CC2531 co-ordinator.

Stage 2. As soon as pairing (of the SLR) has finished, it remains in pairing mode waiting for the SLT to pair with it. So, reset the SLT, place it into pairing mode and observe it pair with the Pi-ve AND the SLR. If this has been successful, then the SLR/SLT will appear in the web frontend Devices list and the SLR status LED will change to solid green.

Zigbee Pairing Instructions for the Hive Active SLR and SLT2/SLT3

While Zigbee2MQTT is still in pairing mode:-

It will, reset, reboot and join the network (check log messages on the web frontend screen).

Check Zigbee Topic SLR

At this point, the controller may not publish a full list of parameters on its root topic pive2mqtt/SLR which are required by Pi-ve's node-RED flow for control. To check these, go to the web frontend screen, select the SLR device and the 'State' tab.

Those required are highlighted. Any additional parameters are unused.

ZigbeeState

To enable any missing information -

On the SLT3 model thermostat:- Press MENU button Select 'Heat' and set to 'Manual' - Then press confirm button

Similarly (for Hot Water):-

Press MENU button Select 'Hot Water' and set to 'Always On' - Then press confirm button

On the SLT2 model thermostat:- Press top right 'menu' button marked + to enable other switches Press Heat function button (marked right arrow) until the status changes to Manual Press Hot Water function button (marked left arrow) until the status changes to Off

node-RED - Import flow

To complete the software setup, copy the node-RED flow at https://github.com/roadsnail/Pi-ve/blob/main/Pi-ve%20flow%20v2-14beta and import it as a new flow in node-RED. Pointing a browser at http://your-pive-ip-address:1880 go to Menu - Import - New flow.

The flow should deploy without warnings/errors and the Pi-ve dashboard should be available by pointing a web browser at http://your-pive-ip-address:1880/ui . If warnings about missing nodes appear, then check that the additional nodes were installed as listed above.

The first time the flow runs, it will check for the existence of two files containing time slot settings. (These files are stored by default in the home directory of the account used to install Node-RED ie. user pi in this tutorial). The files are named Pive-CH and Pve-HW for Central Heating and Hot Water. If these files are not found on first run of the flow, they should be created by the Node-RED catch nodes name No HW! and No CH!.

Pi-ve 1-30b Screenshot

Pi-ve Operation Modes

Set the Man<>Timer switch to 'Man' position OR press the MANUAL ON/OFF - TIMER MODE button (toggles betweeen Manual and Timer Modes). Applicable to CH and HW.

In Manual mode, the HW relay is switched by its Manual Mode - Off/On switch. The state of the relay is indicated by the State LED and the HW Demand icon.

Similarly, the CH relay is switched by its Manual Mode - Off/On switch according to the Thermostat SP setting. The state of the relay is indicated by the State LED and the CH Demand icon.

Set the Man<>Timer switch to 'Timer' position OR press the MANUAL ON/OFF - TIMER MODE button (toggles betweeen Manual and Timer Modes). Applicable to CH and HW.

In Timer mode, the HW relay is automatically switched according to the current HW Time Slot state (see below Timed Off/On Slots). The state of the relay is indicated by the State LED and the HW Demand icon.

Similarly, the CH relay is automatically according to the current CH Time Slot state (see below Timed Off/On Slots). The state of the relay is indicated by the State LED and the CH Demand icon.

Pi-ve Dashboard Timed Off/On Slots (in timer (TMR) Mode)

There are between 1 and a maximum of 8 timed 'On' periods per day for both Heating and Hot Water. Heating and/or Hot Water is 'Off' during the periods between the Time Slots.

By default, the current day's Time Slots are listed under the HW Daily Time Slots and CH Daily Time Slots columns. Pressing a 'Day' button selects all of the Time Slots for a particular day for either Heating or Hot Water.

A Time Slot is selected, (press or click on it in the list), and the Time Slot Start/End Times are displayed in the Edit Time Slot column where they may be changed.

The (selected) Time Slots are modified using the four buttons: SAVE, CANCEL, ADD and DELETE.

The 'C' Button may be used to restore default Time Slots for the whole week and should be used with care. Existing time slot settings will be overwritten with new defaults!

Programming Central Heating Time Slots

Example Time Slot setup for CH to:-

  1. Switch on CH at 06:30 to 20.5 deg C on Monday
  2. 07:45 turn down thermostat to 19 deg C
  3. 08:15 switch off CH
  4. 16:30 turn on CH and set thermostat to 21 deg C
  5. 18:40 turn down thermostat to 19.5 deg C
  6. 22:15 turn off heating

Set - Start = 06:30 End = 07:45 Temp = 20.5 (SAVE)

Set - Start = 07:45 End = 08:15 Temp = 19 (SAVE)

Set - Start = 16:30 End = 18:40 Temp = 21 (SAVE)

Set - Start = 18:40 End = 22:15 Temp = 19.5 (SAVE)

After 22:15, CH will be switched Off until the first (On)Time Slot on Tuesday

Repeat Previous Day's Programme

Want the same programme on Tuesday? Simple -:

Click 'REPEAT PREVIOUS DAY'S PROG'

OVERRIDE Current CH/HW Relay State (in TMR Mode)

In Timer mode, the state of the CH and/or HW relays may be toggled by pressing the CH OVERRIDE TIMER and/or HW OVERRIDE TIMER button. Override will be active from the time the button is pressed until completion of the current Time Slot.

Thus pressing Override Timer while the relevant output is on, will switch it off for the remainder of the current Time Slot duration. Similarly if the output is currently off, then Override will switch it on for the reaminder of the current time slot.

Pressing the relevant Override Active will turn the Override Active LED green. The override duration is shown beneath the LED indicator. The Start time being the time OVERRIDE was activated. The End time will be the current time slot End Time (either On or Off).

Boost Function

The four boost buttons: +30M, +60M, +90M and CANCEL allow CH and/or HW outputs to be turned on for a period of 30, 60 or 90 minutes respectively.

Thus pressing the CH +30M button will set the thermostat setpoint (SP) to 1 degree C higher than the current SLR Thermostat Temperature for 30 minutes. Pressing the HW +30M button will switch the HW output on for a duration of 30 minutes. Similarly the boost time may be 60 or 90 minutes by pressing the appropriate button.

On pressing the boost button, the boost time remaining will be displayed, (the boost countdown), until the (boost) time remaining equals 00:00 and the previous output status is restored.

An active Boost state may be cancelled at any time by pressing the CANCEL button.

Attributions

The following ICONS requiring attribution are used in the Pi-ve dashboard:-

Hot Water Demand Off/On - Icon made by Freepik from www.flaticon.com

Heating Demand Off/On - Icon made by Flat Icons from www.flaticon.com