Hive 3P Plugin - Beta

Getting Started

This is a HomeSeer HS3 plugin for the ‘Hive’ line of thermostats favoured by British Gas (https://www.hivehome.com/ ), this plugin has been developed using the un-official API which is documented on the internet, as such it both uses a cloud service and also an API that may be subject to change at any point. This plugin is to be installed from the updater as any other plugin, unless running the plugin remotely (which there would be no advantage to do so) then HSPI_HIVE3P.exe should be placed inside the main HS directory by the updater. Once the files have been installed by the updater then in the HomeSeer UI go into the Plug-ins > Manage page, you should now see the Hive plugin in the list of plugins. Please now enable this plugin by clicking the switch as you would any other plugin.

As the HomeSeer log suggests, the username and password needs to be set for HomeSeer to communicate with the Hive service. Please note that this is the exact same username and password that you would use if you were to log in to the Hive online service. Please go into Plugins > Hive 3P  > Hive 3P page and you should find three tabs labelled Home, Schedules and Settings. Please click Settings and you should find a page similar to this:

These fields are fairly self explanatory, update the username/password and press update changes. Check the HS log and it should start to get a session key from the Hive service and also a list of your devices. Any suitable devices will be created by HS and appear in the HS UI Please check whether or not the plugin reports that it established a connection and whether or not you have the any errors, if you have then the plugin should now be ready to communicate with.

Devices

HomeSeer will create a group of basic devices for the plugin, the Hive API instead of sending the commands to the thermostat like you might think you instead send them to the receiver. As such you will get a block of devices per receiver found (a receiver that is ‘real’ rather than a synthetic entry). These devices in the main will be self explanatory, you should find that the devices look as follows:

  1. Root Device - This device has limited function but will change it’s state to ‘Error’ if there are communication issues between the plugin and the Hive service.
  2. Boost - This device is the same as the boost button, however the ‘Schedule Lock Time’ is essentially a boost timer. If you set this to 60 minutes and then press boost it will lock the boost on for 60 minutes.
  3. Current Status - This device will be a simple on/off depending on whether the heating relay is currently on/off
  4. Current Temperature - Will only appear for CH receivers, reports the current temperature measured
  5. Holiday Mode - Will show on/off depending on whether or not you are currently in holiday mode or not.
  6. Mode - This will be very similar to the buttons on the thermostat and also in the web control, you can put the heating into manual (or on for hot water), off or to schedule. This device will change value if you change the device outside of HS.
  7. Schedule Lock Time - This device if set does nothing on it’s own, however if you set it and press boost it will lock it out of schedule mode for that period of time, the full capabilities of this are not known.
  8. Target Temperature - Will only appear for CH receivers, will be what is traditionally known as the set point.

All devices contain value/graphics pairs that have been taken from the HomeSeer contemporary image set or have been included in the plugin. You are free to change them to whatever images you feel suitable by editing the pairs in the plugin pages. All of the devices should change status and can be used in events to display screens, obtain images or whatever actions you feel appropriate.

Event Actions/Triggers

The plugin currently exposes all matters by the devices, as such there are no event actions/triggers at this time and control of the thermostats is to be done by devices only.

Issues/Warnings

Scripting Functions

There is one scripting function available in the plugin, this function enables you to return the HTML snippet for the schedule of a thermostat. This is useful for you then to put the HTML into either your own web page or a HSTouch page. The scripting call is ‘schedulereturn’ and accepts two parameters. The first parameter is a true/false parameter as to whether or not you wish to display times on the schedule, the next parameter is the ID for the thermostat. This has to be the long string of numbers that are contained in the device code, when you pass these parameters it should return the entire schedule table in a HTML fragment.

Advanced Configuration

Friendly Names

The thermostats are referred to by device ID number, this number itself is not a particularly easy to interpret number. If you wish to show in the web pages (it will not change devices) that your thermostat has a friendly name then open up the Hive3P.ini file. Add a key at the bottom called [Names] and then add the ID number first, then the name you wish to call it. An example is;

0da5a1e4-b0a5-4428-82c5-0e90baedxxxx=Hot Water

d56e8721-44ba-4842-8c09-bddebbc0xxxx=Downstairs Thermostat

Save the file and it should then call them this in the web pages.

CSS

The schedules have been styled by me and I recognise that these may not be to everyone's tastes. If you wish to change the style (be it font, colours etc) then go into the HomeSeer HTML \ CSS directory and open up the Hive.css file. You are free to style this as you wish however I would recommend keeping a copy of this file in case you change something and want to revert changes. Also note that if you call the scripting function then this CSS file will not be included (as it is in the header), as such you will need to link the Hive.css file in any web pages you use the schedule return in. Alternatively you may wish for a completely new colour scheme if you are using it in a web page and as such you can link to a new CSS file with custom styles.

Issues

Please post any issues/comments/requests to the my email (pending this plugin being released)