View source for Evohome


==Evohome==


evohome is a multi zone wireless heating / hot water controller and associated components e.g.

*Touchscreen Evohome Controller - newest version includes native wifi so separate Remote Gateway (RFG100) no longer required
*Wireless TRVs
*DHW / Room / Outdoor Temperature Sensors
*Boiler / DHW / CH Relays
*OpenTherm Bridge
*Remote Gateway (RFG100)
*Wireless Gateway (HGS80/HGI80)
*UFH Controller
*Zone and Mixing Valves

evohome is for use with hydronic (wet) heating systems and does not typically support electric only systems directly i.e. the boiler & or CH relay will always close to fulfil heat demand. It should however be possible to link a compatible Honeywell wireless thermostat which may allow other possibilities?

evohome can either be used to retrofit an existing system or for implementing a new system wirelessly. Supported CH systems typically correspond with a Honeywell [http://www.home-heating-systems-and-solutions.com/central-heating-design.html Sundial Plan]. There is also a variety of zone / mixing valves / UFH controller as well as the 5A or 10A relays which can be used to create a customised system.

evohome varies from a system with a centrally controlled thermostat in that heat demand is calculated for each zone individually then aggregated via the controller in order to fire the boiler either using 
[http://www.honeywelluk.com/documents/All/pdf/FAQ%20TPI%20Control.pdf TPI] or [http://en.wikipedia.org/wiki/OpenTherm OpenTherm] This is relevant for a multi zone system as there is no guarantee that a central thermostat will correspond to the requirements for an individual zone or the system as a whole when using a variety of changing set points throughout a building.

''Note'': Honeywell has recently started selling its Le Sucre security products under the branding 'evohome security'. They can be controlled from the same app as evohome thermostats and both systems use 868MHz RF but the protocols are completely different and the 'interoperability' happens in the cloud. Evohome security is currently not controllable from Domoticz and the HGI-80 does not 'see' any packets from it.

==Domoticz==


The integration of an Evohome system within Domoticz can be achieved either by communication with the Honeywell servers (Web API or scripting) or by a USB 868MHz device which provides direct communication (Honeywell HGI80 or equivalent). 

'''Overview'''

*Zone device which is a combined temperature and set point device allowing for a temporary, permanent set point override or a return to the schedule.
*DHW device which is as above but allowing control of the hot water on / off state instead of a set point.
*Controller device which allows the control of the controller mode.

The following evohome HGI80 or equivalent enhancements are also available:

*Heat demand logging
*Boiler / CH and DHW relay / heat demand logging
*Linking of non-Evohome room temperature sensor devices

'''ToDo / Possible enhancements'''

*Scheduling support
*Scenes / groups to allow recall of predetermined set points and group control of multiple zones etc.
*Colouring of rooms on the floor plan using the associated set point colour
*Until date for controller mode

==Setup==

===Requirements===

You will need an evohome controller with inbuilt wifi and optionally a HGI80.  Alternatively you can use the older non-wifi evohome controller with v23 firmware or above and either an RFG100 or HGI80. The v23 firmware may well have been the first firmware version that shipped with the non-wifi colour evohome. You should be able to check the firmware version by doing a quick tap on 'settings' on the evohome main screen followed by a long tap (around 15s) on 'device settings'. The system should then display an info screen with the device id and application software version followed by a date etc. There may be a different procedure for other versions of evohome e.g. the mono version.

===Adding Evohome via Web API (recommended for new users)===

Domoticz now has native support for the Evohome Wifi Controller and RFG100 remote gateway using the UK/EMEA client protocol which is currently also advised for use by NA customers.

====Prerequisites====

*You need to have username and password credentials from the evohome web portal https://international.mytotalconnectcomfort.com/Account.

'''Note:''' Do not use a # in your password, this will lead to miscommunication between Domoticz and Evohome
====Adding Evohome Hardware Device to Domoticz====

Use the Domoticz Set-up->Hardware menu and choose the 'Evohome via Web API' device.   

[[File:EvohomeWebHWSettings2.png]]

Enter a name for your system, and your user credentials from the Evohome web portal. By default 'Synchronize installation' will be selected and to complete the installation you should leave it like that. You may either lower or raise the poll intervall to anything you like but if you set it to less than ten seconds it will automatically reset itself to 60 seconds.

After pressing the 'Add' button to add the hardware device, the rest of the configuration will occur automatically and you should see your Evohome heating zones (and Hot Water device if you have one) appear in the devices list after about ten seconds. If you like you can now disable 'Synchronize installation'.

The client has an option to show a zone's next scheduled switch point as the 'until' time. The benefit of this is that if you want to override a setpoint the dialogue will be preloaded with that value as the end time for the override - just like the regular Evohome devices.

If you have multiple Evohome installations you may like the two 'location' options. 'Show location' will prefix your zone names with the location name you specified in the Evohome web portal. 'Select location' probably looks a bit puzzling, but this is how Honewell registers your temperature control system, i.e. your (Wifi) Controller. In sequence the numbers represent your selectable locations, gateways (RFG100|Wifi) and temperature control systems. In theory this allows for quite a lot of options, but according to the web portal help there can only be one gateway and temperature control system for each location, so in practice you should only need to worry about the leftmost dropdown selector.

Starting with version 3.7722 you may now also choose to display more detailed temperatures from your Evohome devices than shown on your controller (which is per 0.5⁰C). There is a penalty to this because it requires additional info to be retrieved from the Evohome web portal, so you may not want to do this on slower systems and/or slower internet connections.

====Upgrading from script====

It couldn't be much simpler. Just change the type of your current Evohome hardware from 'Evohome via script' to 'Evohome via Web API' and enter your credentials.

That said, there is of course the issue of the script itself. To start with you'll need to stop it from atttempting to do any further updates. The script also added (invisible) links towards itself to the device properties and we want to get rid of those. From version 3.7675 and up Evohome via Web API can do this for you, but it requires a device name change to trigger this. Luckily this is easily accomplished by enabling 'Show location'. Simply wait for your zone names to change into something like 'My home: Bathroom'. Turn off 'Show location' if you like the name to change back to 'Bathroom'. The script references will now have been deleted.

===Adding Evohome via usb device (HGI80 or equivalent)===

The Honeywell HGI80 is a USB Gateway Interface device which allows direct communication with all Evohome wireless devices (as noted earlier, not the evohome security products).  The HGI80 provides the most complete support of functionality within Domoticz and once the kernel module is loaded and configured in Linux or the driver installed in Windows, the rest of the setup can be done in Domoticz. This includes additional support for relays including TPI control, a simulated outdoor sensor using the WU Domoticz device, open window mode and battery level updates. Current versions of the Linux kernel will detect the serial port automatically. In older versions ''(before 4.4, and before the 4.3.1, 4.2.7, 4.1.14 or 3.14.58 stable releases of older versions)'' the specific vendor & product code alias is not known to the kernel module and must be configured manually. Use the command <code>uname -a</code> to determine the kernel version.

====Device Driver Setup (Linux)====

Use the command <code>lsusb</code> to list the USB bus devices in your system:

<code>
Bus 002 Device 002: ID 10ac:0102 Honeywell, Inc.
</code>

It may be best to try and get this working from the shell first

<pre>
echo 10ac 0102 | sudo tee /sys/bus/usb-serial/drivers/ti_usb_3410_5052_1/new_id
</pre>

Then check your kernel messages with '''dmesg'''

Depending on your distribution you may need to supply a firmware file or enable the appropriate software sources / repository

'''Automatic setup at boot'''

Something like this works under Ubuntu 12.04 (add to /etc/rc.local)

<pre>
modprobe ti_usb_3410_5052  
echo 10ac 0102 > /sys/bus/usb-serial/drivers/ti_usb_3410_5052_1/new_id
</pre>

You can also add '''ti_usb_3410_5052''' to /etc/modules instead of using the modprobe line in /etc/rc.local (the new_id line is still required)

'''Udev sample rule'''

As an alternative to modifying /etc/rc.local etc. above. It's best to use udevadm to obtain the correct parameters when creating a udev rule as examples can often be misleading.

Put the following in a file such as '''46-hgi80_usb.rules''' and cp to '''/etc/udev/rules.d/'''
<pre>
# Rules for hotplugging Honeywell HGI80 USB device
SUBSYSTEM=="usb", ACTION=="add", ATTR{idVendor}=="10ac", ATTR{idProduct}=="0102", NAME="ttyUSB0", RUN+="/sbin/modprobe ti_usb_3410_5052"
SUBSYSTEM=="usb", ACTION=="add", ATTR{idVendor}=="10ac", ATTR{idProduct}=="0102", NAME="ttyUSB0", RUN+="/bin/sh -c 'echo 10ac 0102 > /sys/bus/usb-serial/drivers/ti_usb_3410_5052_1/new_id'"
KERNEL=="ttyUSB[0-9]*", ATTRS{idVendor}=="10ac", ATTRS{idProduct}=="0102", NAME="ttyUSB0", SYMLINK="ttyUSB.Evo0", GROUP="dialout", MODE="0660"
</pre>

The above was also designed to give a fixed tty number to the device via the NAME parameter (I'm not sure if it required on the first 2 lines). It should therefore be possible to remove the NAME parameter and just accept whatever tty device the kernel assigns. The last line may not be required if you don't want a fixed tty device number. See also [[PersistentUSBDevices]] for restrictions on dev name.

''Note: NAME attribute has no effect on some linux platforms.''

'''Sample kernel output'''

<pre>
usbcore: registered new interface driver ti_usb_3410_5052
usbserial: USB Serial support registered for TI USB 3410 1 port adapter
usbserial: USB Serial support registered for TI USB 5052 2 port adapter
ti_usb_3410_5052 2-1:1.0: TI USB 3410 1 port adapter converter detected
ti_usb_3410_5052: probe of 2-1:1.0 failed with error -5
ti_usb_3410_5052 2-1:2.0: TI USB 3410 1 port adapter converter detected
usb 2-1: TI USB 3410 1 port adapter converter now attached to ttyUSB0
</pre>

Once the module is correctly configured a serial device such as /dev/ttyUSB0 is created. This can then be setup in Domoticz by adding a new hardware device '''Evohome USB (for HGI/S80)''' and choosing the appropriate serial port. The rest of the configuration will occur automatically after a few minutes providing the wireless signal is acceptable.

'''RFBee / Arduino'''

For advanced (or adventurous) users there is a Domoticz compatible firmware for the RFBee (Arduino compatible) device. You will probably need an UartSBee for the USB connection to go with that. Due to the high level of interrupts the FTDI USB device is know to be problematic on the RPi although there may be some workarounds for this now. Likewise it can cause issues with virtualization environments such as VirtualBox. The HGI80 uses a different USB serial device which seems to have less issues.

More details available at https://github.com/fullTalgoRythm/EvohomeWirelessFW

'''Temperature Sensor'''

If you really like to experiment there is also an RFBee firmware to create a evohome compatible room temperature sensor. This is all guess work but working ok so far.

More details available at https://github.com/fullTalgoRythm/EvohomeTemperatureSensor.git

'''Obsolete solutions'''

Things that don't seem to work are module options. This may depend on the age of your kernel and the distribution you use. 

Check module parameters

<code>
modinfo ti_usb_3410_5052 | grep ^parm:
</code>

Variations on the following don't do anything as the relevant module parameters are no longer supported. You have to use new_id as above instead.

<code>
add options ti_usb_3410_5052 vendor_3410=0x10ac product_3410=0x0102
</code>

====Device Driver Setup (Windows)====

Contributed by Heimiko

*download driver at http://www.ti.com/product/TUSB3410/toolssoftware#softTools - TI WDF USBUART Single Driver (Rev. A)
*extract the archive
*in device manager, lookup the hardware ID of your HGI80 (TUSB3410 Boot Device)
*edit the usbuart3410.inf file (either the 32-bit or 64-bit)
*add your hardware ID multiple times in the different section in the INF file
*add the descriptor at the bottom of the INF
*save / exit
*since we've modified the INF file, windows will complain about driver signing / tampering,

so before you can assign this driver to "TUSB3410 Boot Device", you'll need to set windows in test mode (google this if you don't know how)

Its always easier to have an example, so here's a modified [http://www.domoticz.com/forum/viewtopic.php?f=5&t=4072&start=60#p37318 usbuart3410.inf (x64)]
this INF works with my HGI80, I don't know if it'll work with any other (match the hardware/vendor ID's)

lines I added in the different sections:
<pre>
%0102.DeviceDesc%=umpusbvista, USB\VID_10AC&PID_0102
</pre>

then descriptor:
<pre>
0102.DeviceDesc = "Honeywell HGI80"
</pre>

====Adding Evohome Hardware Device to Domoticz====

Use the Domoticz Set-up->Hardware menu and choose the 'Evohome USB (for HGI/S80)' device.   

[[File:Hardware_Device.jpg]]

Enter a name for your system, select the correct serial port and baud rate for your device.  Note: the HGI80 uses a baud rate of 115200, the other baud rates are for alternative devices e.g. RFBee. There is also the option to enter the Controller ID for your Evohome controller and this ensures that messages from neighbouring systems do not cause intereference.  A hexadecimal value should be entered and the ID of your controller can be obtained by pressing the 'Device Settings' button for 10sec (wifi model). 

[[File:Hardware_Settings.jpg]]

After pressing the 'Add' button to add the hardware device, the rest of the configuration will occur automatically and after a few minutes additional Evohome devices will begin to appear in the devices list.  Note: it can take more than 1 hour for all devices to appear in the devices list as the automatic device detection relies on each device sending a message and some device types communicate very infrequently.  For installations with at least one HR92 radiator controller, pressing the button on a HR92 triggers the device to send its zone name and this can also help fix device names (choose the HR92 with the lowest zone number as the process triggers its zone name and all higher numbered zones to send their names too).

====Additional Features====

=====Outdoor Sensor===== 

Note: this functionality is not available with the Evohome Wifi Controller. However, the latest firmware for the WiFi Controller automatically displays the outside temperature based on data obtained from Honeywell servers for the street address to which the device is registered.

Use the default WU setup and naming.

Make sure that no other devices are called 'Outside' just the temperature / baro which should default to 'Outside' for the name. Obviously your WU devices must all be working and reporting sensible values. You may be able to substitue another temperature device in but make sure only the one you want to use is called 'Outside' and rename any others.

[[File:evohome-WU-default.png]]

''Weather Underground Devices''

Put your evohome controller in binding mode

*Press and hold the settings button on the evohome controller screen until the system configuration prompt comes up and then choose the green tick (1)
*Choose system devices (2)
*Then outdoor sensor (3)
*Outdoor sensor again (4)
*Which should bring up the binding screen on evohome (5)

[[File:evohome-outdoor-sensor.png]]

''evohome controller outdoor sensor binding mode''

Once you're at screen 5. then push the button in Domoticz (under Setup/Hardware).

[[File:evohome-hardware.png]]

''Domoticz evohome outdoor sensor bind button''

Success or failure should be reported both on the controller and Domoticz. You need to wait about 3 minutes for the first update.

It looks like this when you're done.

[[File:evohome-outdoor-temp.png]]

''evohome outdoor temperature''

=====Non-Evohome Temperature Sensors=====

This provides the functionality to use any Domoticz temperature device as a remote temperature sensor for an Evohome zone. 

On the Evohome controller: press and hold the settings button to get into the set-up menu. Choose 'Zone Configuration' and then select the zone you want to link to the temperature sensor. Choose the 'Temperature Sensor' option, then 'Remote Sensor' and accept the replace/re-bind message. The controller will now be waiting for the binding message.

In Domoticz, choose the Hardware option in the Setup tab and click on the 'Bind Temp Sensor' button. After a few seconds you should see a confirmation in Domoticz and on the controller that the binding was successful.

[[File:AllSensors_Button.jpg]]

Click on the devices list in Domoticz and you should see the new Evohome zone temperature device labelled 'Unknown' with a zone (Unit) number in the range 40-51 (this allows for remote sensors on all 12 zones if required). You now need to rename this device giving it exactly the same name as the temperature sensor you want to link. After about 5min you should start to see the zone displaying the remote sensor temperature value on the Evohome controller and in Domoticz. 

Note: if the binding process fails, delete the redundant new zone temperature device and then try the binding again. It's recommend to wait at least 1 hour after starting Domoticz before setting up this functionality.  This ensures that all devices have been detected and prevents conflicting device IDs.  Re-binding the original Evohome temperature sensor on the controller disables this functionality and the additional device can be deleted from the devices list.

=====All Sensors for Multi-device Zones=====

For set-ups with multiple devices (e.g. HR92s) grouped into zones (either a multi-room or single-room zone set-up) or where you have a separate temperature sensors (e.g. DTS92).  Enabling this functionality adds separate devices for every device within the Evohome set-up which enables the monitoring and comparison of the temperature of each individual device.  This can be helpful when troubleshooting the set-up of multi-device zones and selecting the appropriate master temperature sensor or just simply if you're interested in seeing the temperature profile of each individual device within the zone.

To enable the functionality: from the Hardware tab click on the 'All Sensors' button 

[[File:AllSensors_Button.jpg]]

This triggers the process of adding an individual zone temperature device for every unique sensor detected by the HGI80. The new devices all have Unit(zone) numbers 13 and higher and labelled 'Zone #' where # is the zone group defined on the controller (the Unit(zone) number is the original zone value offset by 12). If there are multiple sensors within one zone these will all have the same name and Unit numbers, but unique IDs. Note: it can take approximately 1 hour for all devices to appear as some send messages very infrequently.

Example devices list showing 'All Sensors' devices (zones 4,8,10 and 11 are multi-room zones with 2 HR92s in each):

[[File:AllSensors.jpg]]

To disable this functionality, select and delete all the devices with Unit values in the range 13-24.

===Adding Evohome via scripting (web)===

If you wish to use the version supporting the Evohome Wifi Controller or RFG100 remote gateway you will need Python and the [https://github.com/watchforstock/evohome-client evohome-client] installed. There are 2 versions of the client one for NA and one for EMEA. I've created these scripts around the 2nd version of the client which is for EMEA. The scripts would need to be re-worked for the other client.

'''Prerequisites'''

This may be incomplete please update as required...

<code>
sudo apt-get install git python-simplejson python-setuptools python-pip python-dateutil
</code>

Ubuntu 12.04 '''python-requests''' may be out of date please use pip

<code>
sudo pip install requests
</code>

Use git to clone the [https://github.com/watchforstock/evohome-client evohome-client]

<code>
git clone https://github.com/watchforstock/evohome-client.git
</code>

You should be able to install the client using pip or it is also possible to run all the scripts from the evohome-client directory

<code>
sudo pip install ./evohome-client
</code>

You then need to create the following scripts in an appropriate location on the Domoticz server (you can put them in the evohome-client directory after running the git clone). 

'''evoconfig.py'''

<pre>
#fill in username
usr=''
#fill in pw 
pw=''
#fill in Domoticz URL
url='127.0.0.1'
#fill in Domoticz port
port='8080'
#fill in script root e.g. script:///home/<user>/evohome-client script::///usr/local/bin etc
srt='script://'
</pre>

*You need to update '''usr''' and '''pw''' with your username and password credentials from the evohome web portal https://www.mytotalconnectcomfort.com/.
*You also need to update '''srt''' with the location you are using to store the script files '''do not end this with a /'''
*As these need to be installed on the Domoticz server there should not ordinarily be any need to update the url although the '''port''' can be changed if required.

There are two versions of the evo-update script. The first when no username and password are needed for Domoticz. The second when you '''do''' need a user and password.

'''evo-update.sh without Domoticz User and Password'''

<pre>
#!/usr/bin/python
#
# Copyright 2015 - fullTalgoRythm
# 
# Licensed under GNU General Public License 3.0 or later. 
# Some rights reserved. See COPYING, AUTHORS.
# 
# @license GPL-3.0+ <http://spdx.org/licenses/GPL-3.0+>
#
# see http://www.domoticz.com/wiki/Evohome
# see http://evohome-client.readthedocs.org/en/latest/index.html
#

import evoconfig
from evohomeclient2 import EvohomeClient
import evohomeclient
import requests
import json
import datetime
import base64
import os
import sys, traceback

if os.path.isfile("/var/tmp/evo-noup.tmp"):
	os.remove("/var/tmp/evo-noup.tmp")
	sys.exit(1)
	
#connect to evohome web portal @ http://www.mytotalconnect.com
client = EvohomeClient(evoconfig.usr,evoconfig.pw)
#also connect to V1 API to fetch more accurate temperature readings
client1 = evohomeclient.EvohomeClient(evoconfig.usr,evoconfig.pw)
fi=client.full_installation()
systemId=fi['gateways'][0]['temperatureControlSystems'][0]['systemId']
modelType=fi['gateways'][0]['temperatureControlSystems'][0]['modelType']
status=client.locations[0].status()
tcs=status['gateways'][0]['temperatureControlSystems'][0]
zones=tcs['zones']
currentmode=tcs['systemModeStatus']['mode']

createdev=False
updatedev=True

hwname="evohome"
if len(sys.argv)>1:
	mode=sys.argv[1]
	if mode=="init":
		createdev=True
		if len(sys.argv)>2:
			hwname=sys.argv[2]
	elif mode=="quick":
		updatedev=False

if createdev:
	#create evohome script hardware
	r=requests.get("http://%s:%s/json.htm?type=command&param=addhardware&htype=40&port=1&name=%s&enabled=true&datatimeout=0" % (evoconfig.url,evoconfig.port,hwname))

#find last added evohome script hw
r=requests.get("http://%s:%s/json.htm?type=hardware" % (evoconfig.url,evoconfig.port))
hwl=json.loads(r.text)
hwid=-1
for hw in hwl['result']:
	if hw['Type']==40:
		hwid=int(hw['idx'])
if hwid==-1:
	print "ERROR: evohome hardware not found"
	sys.exit(1)

if createdev:
	#create evohome controller device
	r=requests.get("http://%s:%s/json.htm?type=createevohomesensor&idx=%d&sensortype=69" % (evoconfig.url,evoconfig.port,hwid))
	#create evohome dhw device
	r=requests.get("http://%s:%s/json.htm?type=createevohomesensor&idx=%d&sensortype=71" % (evoconfig.url,evoconfig.port,hwid))
	#create evohome zones - create all 12 as helpful if they are sequential
	for i in range(12):
		r=requests.get("http://%s:%s/json.htm?type=createevohomesensor&idx=%d&sensortype=70" % (evoconfig.url,evoconfig.port,hwid))

#update evohome devices with default name, id for portal access and correct location/name of script to run
r=requests.get("http://%s:%s/json.htm?type=devices&displayhidden=1&used=all" % (evoconfig.url,evoconfig.port))
devl=json.loads(r.text)
for dev in devl['result']:
	if dev['HardwareID']==hwid:
		if dev['SubType']=='Evohome':
			if updatedev:
				r=requests.get("http://%s:%s/json.htm?type=setused&idx=%s&deviceid=%s&used=true&name=%s&strparam1=%s" % (evoconfig.url,evoconfig.port,dev['idx'],systemId,modelType,base64.urlsafe_b64encode('%s/evo-setmode.sh {status}' % (evoconfig.srt))))
			r=requests.get("http://%s:%s/json.htm?type=command&param=switchmodal&idx=%s&status=%s&action=0&ooc=1" % (evoconfig.url,evoconfig.port,dev['idx'],currentmode))
		elif dev['SubType']=='Hot Water' and 'dhw' in tcs:
			dhw=tcs['dhw']
			if updatedev:
				r=requests.get("http://%s:%s/json.htm?type=setused&idx=%s&deviceid=%s&used=true&name=%s&strparam1=%s" % (evoconfig.url,evoconfig.port,dev['idx'],dhw['dhwId'],"Hot Water",base64.urlsafe_b64encode('%s/evo-setdhw.sh {deviceid} {mode} {state} {until}' % (evoconfig.srt))))
			zonemode=dhw['stateStatus']['mode']
			if currentmode=="HeatingOff" or currentmode=="AutoWithEco" or currentmode=="Custom":# dhw has no economy mode and does not turn off for heating off also appears custom does not support the dhw zone
				currentmode="Auto"
			if zonemode=="FollowSchedule":
				zonemode=currentmode
			# Fetch the measured temperature from the V1 API for increased resolution. Match zones between both API's via id/dhwId.
			temp=dhw['temperatureStatus']['temperature']
			for zonetemp in client1.temperatures():
				if int(zonetemp['id'])==int(dhw['dhwId']):
					temp=zonetemp['temp']
					break
			req="http://%s:%s/json.htm?type=command&param=udevice&idx=%s&nvalue=0&svalue=%s;%s;%s" % (evoconfig.url,evoconfig.port,dev['idx'],temp,dhw['stateStatus']['state'],zonemode)
			if zonemode=="TemporaryOverride":
				req+=";%s" % (dhw['stateStatus']['until'])
                	r=requests.get(req)
		elif dev['SubType']=='Zone' and dev['Unit']<=len(zones):
			zone=zones[dev['Unit']-1]
			if updatedev:
				r=requests.get("http://%s:%s/json.htm?type=setused&idx=%s&deviceid=%s&used=true&name=%s&strparam1=%s" % (evoconfig.url,evoconfig.port,dev['idx'],zone['zoneId'],zone['name'],base64.urlsafe_b64encode('%s/evo-settemp.sh {deviceid} {mode} {setpoint} {until}' % (evoconfig.srt))))
		        if not zone['temperatureStatus']['isAvailable']:
                		continue
		        zonemode=zone['heatSetpointStatus']['setpointMode']
		        #for custom mode the rooms are assignable so ideally we need to check the schedule and see if the room is assigned or not
		        if zonemode=="FollowSchedule" or currentmode=="HeatingOff": #heating off doesn't support override i.e. heating is permanently switched off
		                zonemode=currentmode
			# Fetch the measured temperature from the V1 API for increased resolution. Match zones between both API's via id/zoneId.
			temp=zone['temperatureStatus']['temperature']
			for zonetemp in client1.temperatures():
				if int(zonetemp['id'])==int(zone['zoneId']):
					temp=zonetemp['temp']
					break
			req="http://%s:%s/json.htm?type=command&param=udevice&idx=%s&nvalue=0&svalue=%s;%s;%s" % (evoconfig.url,evoconfig.port,dev['idx'],temp,zone['heatSetpointStatus']['targetTemperature'],zonemode)
		        if zonemode=="TemporaryOverride":
		               req+=";%s" % (zone['heatSetpointStatus']['until'])
                	r=requests.get(req)

if createdev:
	print "Your evohome zones should now be available in the Domoticz"
</pre>

'''evo-update.sh with Domoticz user and password'''

Find and replace all '''DomoticzUser''' and '''DomoticzPw''' entries in the script below with your own credentials.

<pre>
#!/usr/bin/python
#
# Copyright 2015 - fullTalgoRythm
# 
# Licensed under GNU General Public License 3.0 or later. 
# Some rights reserved. See COPYING, AUTHORS.
# 
# @license GPL-3.0+ <http://spdx.org/licenses/GPL-3.0+>
#
# see http://www.domoticz.com/wiki/Evohome
# see http://evohome-client.readthedocs.org/en/latest/index.html
#

import evoconfig
from evohomeclient2 import EvohomeClient
import evohomeclient
import requests
import json
import datetime
import base64
import os
import sys, traceback

if os.path.isfile("/var/tmp/evo-noup.tmp"):
	os.remove("/var/tmp/evo-noup.tmp")
	sys.exit(1)
	
#connect to evohome web portal @ http://www.mytotalconnect.com
client = EvohomeClient(evoconfig.usr,evoconfig.pw)
#also connect to V1 API to fetch more accurate temperature readings
client1 = evohomeclient.EvohomeClient(evoconfig.usr,evoconfig.pw)
fi=client.full_installation()
systemId=fi['gateways'][0]['temperatureControlSystems'][0]['systemId']
modelType=fi['gateways'][0]['temperatureControlSystems'][0]['modelType']
status=client.locations[0].status()
tcs=status['gateways'][0]['temperatureControlSystems'][0]
zones=tcs['zones']
currentmode=tcs['systemModeStatus']['mode']

createdev=False
updatedev=True

hwname="evohome"
if len(sys.argv)>1:
	mode=sys.argv[1]
	if mode=="init":
		createdev=True
		if len(sys.argv)>2:
			hwname=sys.argv[2]
	elif mode=="quick":
		updatedev=False

if createdev:
	print "het werkt"
	#create evohome script hardware
#	r=requests.get("http://%s:%s/json.htm?type=command&param=addhardware&htype=40&port=1&name=%s&enabled=true&datatimeout=0" % (evoconfig.url,evoconfig.port,hwname))
	r=requests.get("http://%s:%s/json.htm?type=command&param=addhardware&htype=40&port=1&name=%s&enabled=true&datatimeout=0" % (evoconfig.url,evoconfig.port,hwname), auth=('DomoticzUser','DomoticzPw'))

#find last added evohome script hw
#r=requests.get("http://%s:%s/json.htm?type=hardware" % (evoconfig.url,evoconfig.port))
r=requests.get("http://%s:%s/json.htm?type=hardware" % (evoconfig.url,evoconfig.port), auth=('DomoticzUser','DomoticzPw'))

hwl=json.loads(r.text)
hwid=-1
for hw in hwl['result']:
	if hw['Type']==40:
		hwid=int(hw['idx'])
if hwid==-1:
	print "ERROR: evohome hardware not found"
	sys.exit(1)

if createdev:
	#create evohome controller device
	r=requests.get("http://%s:%s/json.htm?type=createevohomesensor&idx=%d&sensortype=69" % (evoconfig.url,evoconfig.port,hwid), auth=('DomoticzUser','DomoticzPw'))
	#create evohome dhw device
	r=requests.get("http://%s:%s/json.htm?type=createevohomesensor&idx=%d&sensortype=71" % (evoconfig.url,evoconfig.port,hwid), auth=('DomoticzUser','DomoticzPw'))
	#create evohome zones - create all 12 as helpful if they are sequential
	for i in range(12):
		r=requests.get("http://%s:%s/json.htm?type=createevohomesensor&idx=%d&sensortype=70" % (evoconfig.url,evoconfig.port,hwid), auth=('DomoticzUser','DomoticzPw'))

#update evohome devices with default name, id for portal access and correct location/name of script to run
r=requests.get("http://%s:%s/json.htm?type=devices&displayhidden=1&used=all" % (evoconfig.url,evoconfig.port), auth=('DomoticzUser','DomoticzPw'))
devl=json.loads(r.text)
for dev in devl['result']:
	if dev['HardwareID']==hwid:
		if dev['SubType']=='Evohome':
			if updatedev:
				r=requests.get("http://%s:%s/json.htm?type=setused&idx=%s&deviceid=%s&used=true&name=%s&strparam1=%s" % (evoconfig.url,evoconfig.port,dev['idx'],systemId,modelType,base64.urlsafe_b64encode('%s/evo-setmode.sh {status}' % (evoconfig.srt))), auth=('DomoticzUser','DomoticzPw'))
			r=requests.get("http://%s:%s/json.htm?type=command&param=switchmodal&idx=%s&status=%s&action=0&ooc=1" % (evoconfig.url,evoconfig.port,dev['idx'],currentmode), auth=('DomoticzUser','DomoticzPw'))
		elif dev['SubType']=='Hot Water' and 'dhw' in tcs:
			dhw=tcs['dhw']
			if updatedev:
				r=requests.get("http://%s:%s/json.htm?type=setused&idx=%s&deviceid=%s&used=true&name=%s&strparam1=%s" % (evoconfig.url,evoconfig.port,dev['idx'],dhw['dhwId'],"Hot Water",base64.urlsafe_b64encode('%s/evo-setdhw.sh {deviceid} {mode} {state} {until}' % (evoconfig.srt))), auth=('DomoticzUser','DomoticzPw'))
			zonemode=dhw['stateStatus']['mode']
			if currentmode=="HeatingOff" or currentmode=="AutoWithEco" or currentmode=="Custom":# dhw has no economy mode and does not turn off for heating off also appears custom does not support the dhw zone
				currentmode="Auto"
			if zonemode=="FollowSchedule":
				zonemode=currentmode
			# Fetch the measured temperature from the V1 API for increased resolution. Match zones between both API's via id/dhwId.
			temp=dhw['temperatureStatus']['temperature']
			for zonetemp in client1.temperatures():
				if int(zonetemp['id'])==int(dhw['dhwId']):
					temp=zonetemp['temp']
					break
			req="http://%s:%s/json.htm?type=command&param=udevice&idx=%s&nvalue=0&svalue=%s;%s;%s" % (evoconfig.url,evoconfig.port,dev['idx'],temp,dhw['stateStatus']['state'],zonemode)
			if zonemode=="TemporaryOverride":
				req+=";%s" % (dhw['stateStatus']['until'])
                	r=requests.get(req, auth=('DomoticzUser','DomoticzPw'))
		elif dev['SubType']=='Zone' and dev['Unit']<=len(zones):
			zone=zones[dev['Unit']-1]
			if updatedev:
				r=requests.get("http://%s:%s/json.htm?type=setused&idx=%s&deviceid=%s&used=true&name=%s&strparam1=%s" % (evoconfig.url,evoconfig.port,dev['idx'],zone['zoneId'],zone['name'],base64.urlsafe_b64encode('%s/evo-settemp.sh {deviceid} {mode} {setpoint} {until}' % (evoconfig.srt))), auth=('DomoticzUser','DomoticzPw'))
		        if not zone['temperatureStatus']['isAvailable']:
                		continue
		        zonemode=zone['heatSetpointStatus']['setpointMode']
		        #for custom mode the rooms are assignable so ideally we need to check the schedule and see if the room is assigned or not
		        if zonemode=="FollowSchedule" or currentmode=="HeatingOff": #heating off doesn't support override i.e. heating is permanently switched off
		                zonemode=currentmode
			# Fetch the measured temperature from the V1 API for increased resolution. Match zones between both API's via id/zoneId.
			temp=zone['temperatureStatus']['temperature']
			for zonetemp in client1.temperatures():
				if int(zonetemp['id'])==int(zone['zoneId']):
					temp=zonetemp['temp']
					break
			req="http://%s:%s/json.htm?type=command&param=udevice&idx=%s&nvalue=0&svalue=%s;%s;%s" % (evoconfig.url,evoconfig.port,dev['idx'],temp,zone['heatSetpointStatus']['targetTemperature'],zonemode)
		        if zonemode=="TemporaryOverride":
		               req+=";%s" % (zone['heatSetpointStatus']['until'])
                	r=requests.get(req, auth=('DomoticzUser','DomoticzPw'))

if createdev:
	print "Your evohome zones should now be available in the Domoticz"
</pre>

'''Make it executable after you have created it'''

<code>
chmod +x evo-update.sh
</code>

'''Create the initial Domoticz hardware device and zones make sure Python and the evohome-client are installed before running this'''

<code>
evo-update.sh init
</code>

or to specify the name of the hardware in Domoticz

<code>
evo-update.sh init <hardware-name>
</code>

*You need to run this one time only to get the appropriate devices setup and configured make sure evo-config.py has the correct setting before running
*You can run this again if something goes wrong but it will add a new hardware controller in Domoticz each time so you will need to remove the old one manually

'''Update dhw, zone temperatures and controller mode only (no zones names, zone ids, script settings etc)'''

<code>
evo-update.sh quick
</code>

'''Regular update of evohome zone temperatures, zone names etc.'''

<code>
evo-update.sh
</code>

'''Schedule this to run once every minute using crontab'''

Try if the script works from the commandline: <script_root>/evo-update.sh

For example: /home/pi/evohome-client/evo-update.sh


If it doesn't try: python <script_root>/evo-update.sh

For example: python /home/pi/evohome-client/evo-update.sh


<code>
crontab -e
</code>

You need to add the following line making sure to replace '''<script_root>''' with your script install location

<pre>
*/1 * * * * <script_root>/evo-update.sh
</pre>
or
<pre>
*/1 * * * * python <script_root>/evo-update.sh
</pre>

'''evo-setmode.sh'''

<pre>
#!/usr/bin/python
#
# Copyright 2015 - fullTalgoRythm
# 
# Licensed under GNU General Public License 3.0 or later. 
# Some rights reserved. See COPYING, AUTHORS.
# 
# @license GPL-3.0+ <http://spdx.org/licenses/GPL-3.0+>
#
# see http://www.domoticz.com/wiki/Evohome
# see http://evohome-client.readthedocs.org/en/latest/index.html
#

import evoconfig
from evohomeclient2 import EvohomeClient

import sys
from datetime import datetime

#connect to evohome web portal @ http://www.mytotalconnect.com
client = EvohomeClient(evoconfig.usr,evoconfig.pw)
status=client.locations[0].status()
tcs=status['gateways'][0]['temperatureControlSystems'][0]
zones=tcs['zones']
currentmode=tcs['systemModeStatus']['mode']

modeuntil=None
if len(sys.argv)>2:
	modeuntil = datetime.strptime(sys.argv[2], '%Y-%m-%dT%H:%M:%S+0000')

newmode=sys.argv[1]
#guess this supports multiple gateways and tcs
if currentmode!=newmode:
	if newmode=="Away":
		client.set_status_away(until=modeuntil)
	elif newmode=="AutoWithEco":
		client.set_status_eco(until=modeuntil)
	elif newmode=="DayOff":
		client.set_status_dayoff(until=modeuntil)
	elif newmode=="Custom":
		client.set_status_custom(until=modeuntil)
	elif newmode=="Auto":
		client.set_status_normal()
	elif newmode=="HeatingOff":
		client.set_status_heatingoff(until=modeuntil)
	open ("/var/tmp/evo-noup.tmp","w")
</pre>

'''Make it executable after you have created it'''

<code>
chmod +x evo-setmode.sh
</code>

'''evo-settemp.sh'''

<pre>
#!/usr/bin/python
#
# Copyright 2015 - fullTalgoRythm
# 
# Licensed under GNU General Public License 3.0 or later. 
# Some rights reserved. See COPYING, AUTHORS.
# 
# @license GPL-3.0+ <http://spdx.org/licenses/GPL-3.0+>
#
# see http://www.domoticz.com/wiki/Evohome
# see http://evohome-client.readthedocs.org/en/latest/index.html
#

import evoconfig
from evohomeclient2 import EvohomeClient
import sys
import dateutil.parser

if len(sys.argv)<5:
        until = None
elif sys.argv[4][:1] == '0':
        until = None
else:
     	until = dateutil.parser.parse(sys.argv[4]).strftime('%Y-%m-%dT%H:%M:%SZ')

#connect to evohome web portal @ http://www.mytotalconnect.com
client = EvohomeClient(evoconfig.usr,evoconfig.pw)
client._get_single_heating_system().zones_by_id[sys.argv[1]]._set_heat_setpoint({"HeatSetpointValue":0.0 if len(sys.argv)<4 else float(sys.argv[3]),"SetpointMode":int(sys.argv[2]),"TimeUntil":until})
open ("/var/tmp/evo-noup.tmp","w")
</pre>

'''Make it executable after you have created it'''

<code>
chmod +x evo-settemp.sh
</code>

'''evo-setdhw.sh'''

<pre>
#!/usr/bin/python
#
# Copyright 2015 - fullTalgoRythm
# 
# Licensed under GNU General Public License 3.0 or later. 
# Some rights reserved. See COPYING, AUTHORS.
# 
# @license GPL-3.0+ <http://spdx.org/licenses/GPL-3.0+>
#
# see http://www.domoticz.com/wiki/Evohome
# see http://evohome-client.readthedocs.org/en/latest/index.html
#

import evoconfig
from evohomeclient2 import EvohomeClient
import sys
import dateutil.parser

if len(sys.argv)<5:
        until = None
elif sys.argv[4][:1] == '0':
        until = None
else:
     	until = dateutil.parser.parse(sys.argv[4]).strftime('%Y-%m-%dT%H:%M:%SZ')

#connect to evohome web portal @ http://www.mytotalconnect.com
client = EvohomeClient(evoconfig.usr,evoconfig.pw)
client._get_single_heating_system().hotwater._set_dhw({"State":0 if len(sys.argv)<4 else sys.argv[3],"Mode":int(sys.argv[2]),"UntilTime":until})
open ("/var/tmp/evo-noup.tmp","w")
</pre>

'''Make it executable after you have created it'''

<code>
chmod +x evo-setdhw.sh
</code>

==Functionality==

===Temperature Devices - Zone Temperature Monitoring and Control (Scripting and HGI80)===

Example devices list showing controller and temperature sensors.  These devices provide the ability to monitor the temperature of each zone and control the setpoint temperatures either within individual zones or of the entire system via the controller. 

[[File:Temperature Devices.jpg]]

Example temperature display:

[[File:Temperature.jpg]]

===Switch Devices - Heat Demand Monitoring (HGI80 only)===

Example devices list showing heat demand (Relay) switch devices. These devices provide the ability to monitor the heat demand within each zone and also the boiler, CH and DHW demand.

[[File:Switch Devices.jpg]]

Example switches display showing heat demand (Office zone calling for heat, Boiler and CH Valve On with sliders showing demand level).  
[[File:Demand - Switches2.jpg]]

Historical heat demand data for each device can be viewed graphically by selecting switch Log.

[[File:Demand pct2.jpg]]

==Notes==

'''Multi Zone'''

evohome is based on Hometronic which has been in production since 2002. It was designed to be a multi zone system from the start which is evidenced by the operation of the TRVs and relays. These respond to the combined demands of the individual zones rather than just that of a central location. If you are thinking about creating your own system it's worth considering how you would deal with issues such as increasing a set point for an individual zone. If the central thermostat has already reached temperature there will be no new heat demand generated by turning up an individual zone. Likewise as the set points and heat demand change for different zones there is no guarantee that this will match the heat demand at the central thermostat. The system may therefore be on too much and waste energy or too little and not heat up properly in all the zones.

It is certainty an expensive system especially when compared to other offerings like eQ-3 MAX! Unfortunately that system is only available in German and unlike evohome little appears to be known about the operating protocols. It would be an interesting exercise to try and create a multi zone heating system and probably quite achievable if you have the time and energy. Until then however evohome remains one of the few multi zone systems with hot water control and monitoring which can also be linked to a home automation system.

'''DHW Kit'''

evohome's DHW implementation includes support for a temperature sensor. In addition to a BDR91 relay the DHW kit includes 2 sensors, a strap on sensor for a traditional hot water cylinder and an insertion sensor for an unvented (pressurised) cylinder such as a Megaflow. The strap on sensor fits as per an equivalent thermostat and the insertion sensor is designed to be fitted in the heat well of an unvented cylinder in place of an immersion heater thermostat (the fitted cylinder thermostat must be left in place).

'''BDR91 Relays'''

The installation notes for the BDR91 relay suggests that for optimum reception a gap of at least 30 cm from anything metal including back boxes should be maintained. Apparently there should also be a 30cm gap from other wireless devices including other BDR91 relays and the DHW sensor. You may also need to ensure any metal objects do not interfere with the signal between the relay and the evohome controller. If retro fitting a system it may be more practical to wire the relays close to the zone values which are often found in the airing cupboard. 

The relays support TPI which generates a more evenly spaced on / off signal proportional to the heat demand (set as a % of the on/off cycle time). This improves comfort by maintaining a more even temperature as well as improving the efficiency of condensing boilers which are designed to recycle waste energy (only possible below a certain return temperature). The relays will go into a fail-safe mode in the absence of a wireless signal and either turn off or maintain a minimum duty cycle depending on the settings. Some Z-Wave wireless thermostat relays do not support TPI.

'''TRVs'''

I've noted that rather than just being open or closed the TRVs will maintain a partially open state when the heat demand is low. This presumably helps to balance the system directing more heat to radiators where the TRVs are fully open i.e. zones where there is greater heat demand. There is some noise to contend with both from the actuator in the TRV and from the water flow when the valves are partially closed. The actuator in the TRV can of course only be heard when the valve position is being adjusted i.e. opened, closed etc. I wouldn't describe the noise as excessive but it is audible. The water flow in a radiator can only be heard when the zone is near the set point temperature and the valve is in a partially closed position and the CH pump is on.

It's worth noting that the actual radiator valves (the TRV normally just sits on top and opens and closes it by pushing down on something) often seize up and may require replacement. These either jam open or closed and prevent the radiators from turning on / off. There are also other common problems such as sludge / dirt and air locks that can stop an individual radiator working properly. A multi zone system is much more inclined to show up these defects.

'''TPI (PID)'''

Afaik TPI is just another term for a [http://en.wikipedia.org/wiki/PID_controller PID controller] which is a method for minimizing error in a feedback loop by a tunable algorithm. In this instance this could be seen as controlling a heating device by trying to keep the resultant temperature as close to the set point as possible.

There is an [http://playground.arduino.cc/Code/PIDLibrary Arduino library] that is designed to implement PID control which includes an example using a temperature sensor as the process variable and relay control for the heating device. This would probably a good place to start for implementing a TPI based thermostat.

'''Debugging'''

If you'd like to see the debug logs for evohome for the HGI80 i.e. so you can view the wireless messages etc you will need to recompile and enable the debug setting in '''hardware/EvohomeBase.cpp''' 

Change the code as follows...

<pre>
//#ifdef _DEBUG
bool CEvohomeBase::m_bDebug=true;
/*#else
bool CEvohomeBase::m_bDebug=false;
#endif*/
</pre>

On Linux this should create an '''evoraw.log''' in the home directory of the user running the domoticz daemon which will depend on your startup script etc.

'''Automation'''

One of the main reasons for integration with Domoticz was to make use of the automation facilities on offer. With the appropriate devices in Domoticz this could for example be based on presence detection, alarm mode, geo fencing etc.

'''Updating the evohome controller mode using the JSON API'''

<code>/json.htm?type=command&param=switchmodal&idx='''<idx>'''&status='''<status>'''&action='''<action>'''&ooc='''<ooc>'''</code>

*'''<idx>''' id number of the evohome controller device in Domoticz
*'''<status>''' Auto,AutoWithReset,AutoWithEco,Away,DayOff,Custom,HeatingOff
*'''<action>''' (1 to run on action script, 0 to disable)
*'''<ooc>''' (1 only trigger the event & log on change, 0 always trigger & log)

'''Specify an until date...'''

<code>/json.htm?type=command&param=switchmodal&idx='''<idx>'''&status='''<status>'''&action='''<action>'''&ooc='''<ooc>'''&until='''<until>'''</code>

*as above
*'''<until>''' ISO date time to run till, most controller modes do not support the time part and will require at least the next day to update. For example '''`date -Iseconds -d "+4 hours"`''' can be used in a bash script.

'''Updating a setpoint using the JSON API'''

<code>/json.htm?type=setused&idx='''<idx>'''&setpoint='''<setpoint>'''&mode='''<mode>'''&used=true</code>

*'''<idx>''' id number of the evohome zone device in Domoticz
*'''<setpoint>''' set point in degrees (will be ignored for Auto)
*'''<mode>''' Auto,TemporaryOverride,PermanentOverride,FollowSchedule
*'''used''' must be true

'''Turning HotWater ON/OFF'''

<code>/json.htm?type=setused&idx='''<idx>'''&setpoint='''<setpoint>'''&state='''<state>'''&mode='''<mode>'''&used=true</code>

*'''<idx>''' id number of the evohome DHW temp in Domoticz
*'''<setpoint>''' set point in degrees (will be ignored)
*'''<state>''' On,Off
*'''<mode>''' Auto,TemporaryOverride,PermanentOverride,FollowSchedule
*'''used''' must be true

'''Specifying a date for TemporaryOverride'''

<code>/json.htm?type=setused&idx='''<idx>'''&setpoint='''<setpoint>'''&mode='''TemporaryOverride'''&until='''<until>'''&used=true</code>

*as above
*'''<until>''' ISO date time for the set point override.

==More info==

[http://evohome.info/ evohome info]
[http://sourceforge.net/p/opentrv/wiki/Honeywell%20Evohome%20System/ OpenTRV]
[http://www.domoticaforum.eu/viewtopic.php?f=7&t=5806 Evohome / Evotouch Wireless protocol]
[[Category:Python]]
[[Category:Bash]]