Hive Thermostat (British Gas) Tutorial

Tags: #<Tag:0x00007f616e7834b8>

A number of people have asked me via PM for how I connect to the British Gas Hive thermostat to openHAB. As such, here is a very brief set of notes and the scripts that I use, to help get any other Hive users started.

Note that these scripts are based on information from http://www.smartofthehome.com/2016/05/hive-rest-api-v6, where the author describes the key steps necessary to connect to the British Gas API for hive. This could of course change at anytime as these are all unofficial…

Also don’t forget to change the extension on the attached file to “.zip”, and then unzip the file.

Overview

Using your Hive userid/password, you can log in to the British Gas servers and get data from your Hive thermostat in JSON format. This data will be quite large, and include all sorts of things that you probably aren’t interested in.

One of the important things to note in this JSON data is that there are a number of ‘nodes’. Each node seems to be for various internal ‘devices’ that your Hive is seeing. In my case, I am seeing 7 nodes in my data. You will have to figure out which of the nodes is for your heating (and which is for hot water, if you control your water from your hive as well). As an aside, there is a node for the water leaking sensor if you have this. However, my scripts do not currently support this.

Basic How-To

  1. Modify the file config with your Hive login data, your openHAB server data and if you want to use mqtt, then your mqtt server data. If you don’t know your hive node numbers and IDs, then leave these as is for now. If you do know them, then put them in here in their respective places and jump to step 8. If you have a combi-boiler, you will probably not have a node for your Water, so the node/receiver IDs for water can be ignored.

  2. Make sure all the files with “.sh” extension are executable (chmod +x *.sh)

  3. If you don’t know your node Ids, run the script nodes2JsnFile.sh. If your login details have been correctly entered in the config file, this will get your data and save to a file called nodes.jsn.

  4. Open the nodes.jsn file. It may be helpful to use something to ‘prettify’ and format the JSON, so that it is easier to read. If your text editor does not do this, there are online sites available that do this. nodes

  5. Search for the exact text "temperature": including the quotation marks and the colon mark. It should only find one instance of this. The node that this is found in is your heating node. Scroll down slightly and you should see the “id” value. This is the id you need to enter in the RECEIVER_ID_HEATING parameter of the config file.

  6. Before moving on, scroll UP and count the node number that this ID is found in, starting at zero for the first node. In the screenshot below, you can see that my heating temperature reporting node is node 4.
    temperature 2

  7. If you have a hot water node, repeat the above step for your hot water node but this time searching for "stateHotWaterRelay":

  8. Put the node numbers and IDs from the previous steps into the config file from step 1.

  9. You can now get the data and post directly to openHAB via REST or to MQTT, using the respective scripts. If you post to openHAB, remember to change the item names to match yours in the hiveToOpenHAB.sh script.

  10. I have also included scripts for ‘boosting’ and for setting the thermostat temperature. I don’t use these much so am not sure how reliable they are, but they certainly worked when I first wrote the scripts (some time ago).

Hope this helps those of you looking to integrate Hive with openHAB!

EDIT: Sorry, I forgot to include the nodes2JsnFile.sh in the zip. I’ve attached it seperately now as with a .css extension to overcome the forum’s limitaiton on filetypes that can be uploaded. Please rename/give permissions accordingly.

hive-openHAB.pdf (8.5 KB)
nodes2JsnFile.css (1.2 KB)


UPDATE: @robkenny has kindly updated/tidied up the scripts and made it much more user friendly. Please see his github - https://github.com/230delphi/openab-hivehome

3 Likes

Should the file “nodes2JsnFile.sh” be included in your zip? I see the other files mentioned but not that one.
I’ve been procrastinating about creating a Hive link for myself, and now I’m glad I did because I can use yours!

Sorry, I missed that. Have just added to the original post.

Hi There,

Both attachments are corrupt for me. Are you able to reupload?

Thanks

I suspect the problem may be at your end? I have just downloaded both files and opened them without any issues. In case you missed it, don’t forget to change the .pdf extension to .zip and the .css to .sh

Hi, I am new to openhab, and am a little confused as to where to go next with getting hive setup.

I have the scripts working. I got my IDs, and configured the node ID. I have run hiveToOpenhab.sh and it reports error":{“message”:“Item CH_Target_Temp does not exist!” among other errors. Which makes sense, as I have not setup any Things yet. Where should I be looking in the docs for something more useful? I am guessing the UI is not going to serve me on this one.

If you look towards the end of that script file, you will see that it is trying to update openHAB items with values from Hive (via openHAB’s REST api). All you need to do is make sure that you have corresponding items defined in openHAB (note that we are talking about items and not things - see http://docs.openhab.org/concepts/items.html).

Smar!
thanks for your work on this. as agreed, I’ve added and made several updates to a version in github.
for anyone whos interested, the read/update scripts supporting multi heating zones and bulbs is now available: https://github.com/230delphi/openab-hivehome

Rob.

1 Like

I am a complete newbie to openHAB and have extremely limited knowledge of coding (99% of what I have done in the past has been by following very clear guides) so I could do with a little assistance getting this working on my RPI3. Apologies in advance if my questions are stupid.

I have downloaded the 2 files (to my windows laptop) and renamed the extensions, do I alter the config file text on my laptop or transfer it to the pi before editing?

If I can edit this before transferring can I just do it with a text editor? assuming so I have already entered the username and password. Will the server data be http://my openHAB IP:XXXX (not sure if the XXXX should be 7070 as in the file or another port)

So once that’s done and assuming I am right in editing the file before transferring, how and where do I move the files to?

If I actually have to transfer the files first how do I open them to edit them

Again very sorry for the lack of knowledge on this, normally I would muddle through trying to find the info on Google but to be honest at the moment I don’t know where to start

You can edit on either machine (though editing on the RPi3 will avoid any potential issues with end of line characters), and yes a simple text editor is all that is necessary.

Port should be whatever you are using in your set up. In my case, for historical reasons I am using 7070, but the default for openHAB is 8080.

Files can go to any folder on your RPi3 that is accessible from your openHAB, e.g. /opt/hive

Having said the above, I suggest you have a look at @robkenny’s script ( https://github.com/230delphi/openab-hivehome). My original scripts were put together in a rush for my own use. Rob has tidied up and made the script much more user friendly.

Thank you for your guidance, I know it must be annoying when people with limited knowledge like myself ask basic questions. I think a Dummies Guide book might be a good purchase for myself.

I will have a read through the other thread

You are most welcome!

Absolutely not at all - it is a pleasure to help where we can. We all had to start somewhere. The important thing is to try and understand what and why, whenever possible, rather than just following a set of steps without understanding. This is the only way to get the most out of a solution like openHAB, which whilst very powerful, can seem initially daunting.

Hi, I have openhab2 installed on a raspberry pi. i currently have it controlling my philips hue lights and my tv through a logitech harmony hub. i have a hive heating system 1 zone and hotwater. im a newbie to this openhab / rasberry pie. is there a genera; tutorial video showing how to install the api’s on the openhab2 / rasberry pi?

i opened the config file using a software called brackets and i filled in my hive login details, my openhab server address where asked.

Where do i get my receiver ID? is this the Hub ID on the back of the hub?
What is the MQTT server for? what extra info do i get on it?

any help would be appreciated.

Thanks,
Paul

I’m not sure what you mean about installing “api’s”. Do you mean “bindings” (https://docs.openhab.org/addons/bindings.html)? If so, bindings can generally be installed from the PaperUI under its extensions menu (https://docs.openhab.org/configuration/paperui.html).

I

I don’t think this is the same ID (I haven’t checked though). Getting the Receiver ID is a bit convoluted - there are some basic instructions in the first post of this thread. However, I suggest you go to the github page by @robkenny (link at the end of the first post). I believe his script makes it easier to get the Receiver ID.

Hi

I have a hive system, with a thermostat (single zone)
Hot water component, although my boiler doesnt support it so its unused
2 door sensors (doesnt seem to be any config for these)
and a coloured light

Before I give this a go, (looks fairly straightforward) can you tell me if anyone is actively working on bringing more functionality to it? ie, setting thermostat etc.
And, if there is a plan to include the door sensors (and other devices not in the items files)

I am interested in assisting with the testing of the device.

Thanks

There is a script in the zip file that allows setting thermostat temperature etc.

I am not sure if anyone is working on extending the functionality beyond what is here, but from my side, I do not have a Hive anymore and so no plans for any further work on this.

@el_Paulio
There is also a node-red node for hive at node-red-contrib-hive
It is pretty much undocumented but I think it could be worth a try

Thanks for the reply

What did you replace your hive with out of interest?
Also, do you still use OpenHAB, and your new thermostat together?

Cool, I’ll take a look see if its worth my time, cheers :+1:

I have moved over to a Honeywell evohome solution (mainly because it gives me greater control over heating in each room with its up to 12 zones, and also because of its zone by zone ‘learning’ of heat-up/cool-down times). And yes, this is fully managed through openHAB.

Here’s a screenshot from one of my openHAB pages:

Is this screen shot the evohome app or OH?
If it is OH can you share you code for it, please?