jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-19 15:26:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add services to evohome (#11422)

Browse Source 
* initial tweaks

* latest changes

* latest changes

* final tweaks

* final tweaks 2

* final tweaks 3

* final tweaks 4

* small tweaks, corrections

* small tweaks, corrections 2

* small tweaks, corrections 3
This commit is contained in:
David Bonnes 2020-01-27 12:57:50 +00:00 committed by Franck Nijhof
parent 3771e19d64
commit 2083057056
1 changed files with 49 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
source/_integrations/evohome.markdown
View File

@ -5,7 +5,8 @@ logo: honeywell.png
ha_category: ha_category:
- Hub - Hub
- Climate - Climate
ha_release: 0.8 - Water Heater
ha_release: 0.80
ha_iot_class: Cloud Polling ha_iot_class: Cloud Polling
ha_codeowners: ha_codeowners:
- '@zxdavb' - '@zxdavb'
@ -13,26 +14,27 @@ ha_codeowners:
The `evohome` integration links Home Assistant with all _non-US_ [Honeywell Total Connect Comfort (TCC)](https://international.mytotalconnectcomfort.com/Account/Login) CH/DHW systems, such as: The `evohome` integration links Home Assistant with all _non-US_ [Honeywell Total Connect Comfort (TCC)](https://international.mytotalconnectcomfort.com/Account/Login) CH/DHW systems, such as:
- The Honeywell evohome CH/DHW system, and - the Honeywell evohome CH/DHW system, and
- The Honeywell Round Thermostat - the Honeywell Round Thermostat
- the Honeywell Mobile Access Kit
It does not support the home security functionality of TCC. It does not support the home security functionality of TCC.
It uses v2 of the [evohome-client](https://github.com/watchforstock/evohome-client) client library. It uses the [evohome-async](https://github.com/zxdavb/evohome-async) client library.
Honeywell removed support for higher-precision temperatures from the v2 API, and thus reported temperatures are rounded up to the nearest 0.5C. If your system is compatible with this integration, then you will be able to access it via [https://international.mytotalconnectcomfort.com/](https://international.mytotalconnectcomfort.com/) (note the `international`).
### evohome ### Evohome
evohome is a multi-zone system. Each zone is represented as a **Climate** device: it will expose the zone's operating mode, temperature and setpoint. Evohome is a multi-zone system. Each zone is represented as a **Climate** entity: it will expose the zone's operating mode, temperature and setpoint.
The controller/location is also represented as a **Climate** device: it will expose the location's operating mode (see below for details). Note that the controller's current temperature is calculated as an average of all the Zones. The location (controller) is also represented as a **Climate** entity: it will expose the location's operating mode (see below for details). Note that the entity's current temperature is calculated as an average of all the Zones.
The DHW controller is represented as a **WaterHeater** device: It will report its current temperature (but not target temperature), and it can be turned on or off. The DHW controller is represented as a **WaterHeater** entity: It will report its current temperature, and it can be turned on or off. The setpoint is not reported, and cannot cannot be changed.
### Round Thermostat ### Round Thermostat
Although Round Thermostat is, strictly speaking, a Controller and a single zone, they are merged into a single **Climate** device. Such systems usually have only one Round Thermostat, although they can have two. Systems with one such thermostat are merged into a single **Climate** entity. Systems with two thermostats will have a 3rd entity for the TCC locations, much like evohome, above.
## Configuration ## Configuration
@ -55,7 +57,7 @@ password:
required: true required: true
type: string type: string
location_idx: location_idx:
description: Used to select which location to use, if your login has access to more than one location. Multiple locations at one time are not supported. description: Used to select which location to use, if your login has access to more than one location. Multiple locations at one time are not officially supported.
required: false required: false
type: integer type: integer
default: 0 default: 0
@ -66,29 +68,55 @@ scan_interval:
default: 300 default: 300
{% endconfiguration %} {% endconfiguration %}
This is an IoT cloud-polling device, and the recommended `scan_interval` is 180 seconds. Testing has indicated that this is a safe interval that - by itself - shouldn't cause you to be rate-limited by Honeywell. This is an IoT cloud-polling integration, and the recommended `scan_interval` is 180 seconds. Testing has indicated that this is a safe interval that - by itself - shouldn't cause you to be rate-limited by Honeywell.
## Operating modes, and inheritance ## System modes, Zone overrides and Inheritance
Zones support only three setpoint modes: **FollowSchedule**, **TemporaryOverride**, and **PermanentOverride**. Evohome locations support up to six distinct operating modes: **Auto**, **AutoWithEco**, **Away**, **DayOff**, **HeatingOff**, and **Custom**. Not all evohome systems support all modes.
Mostly, the zone 'inherits' its functional operating mode from the controller (the actual algorithm for this is a little complicated). Zones support three setpoint modes: **FollowSchedule**, **TemporaryOverride**, and **PermanentOverride** but 'inherit' an operating mode from their location (the actual algorithm for this is a little more complicated than indicated below - please see your vendor's documentation).
The evohome controller supports seven distinct system modes: **Auto**, **AutoWithEco**, **Away**, **DayOff**, **HeatingOff**, and **Custom**; **AutoWithReset** is a hidden mode that will revert all zones to **FollowSchedule** mode. For **FollowSchedule**, a zone's `temperature` (target temperature, a.k.a setpoint) is a function of its scheduled temperature and its inherited mode. For example, **AutoWithEco** would be scheduled temperature less 3C.
If the zone is in **FollowSchedule** mode, its `temperature` (target temperature) is a function of its scheduled temperature and its functional mode - for example, **AutoWithEco** is scheduled temperature less 3C. If the location is set to **HeatingOff** (temperature set to a minimum) or **Away** (temperature set to 12C), then the zones will inherit that setpoint regardless of their own mode. For **Away**, the DHW controller will also be turned off.
If the controller is set to **HeatingOff** (target temperature to a minimum) or **Away** (target temperature to 12C), then the zones will inherit that mode regardless of their own setpoint mode. If the zone's temperature is changed, then it will be a **TemporaryOverride** that will revert to **FollowSchedule** at the next scheduled setpoint (or in an hour, if there is no such schedule). Zones can be switched between the two override modes without changing the target temperature.
If the zone's temperature is changed, then it will be a **TemporaryOverride** that will revert to **FollowSchedule** at the next scheduled setpoint. Once this is done, the zone can be switched to **PermanentOverride** mode. Some locations have a hidden mode, **AutoWithReset**, that will behave as **Auto**, and will reset all zones to **FollowSchedule**.
In Home Assistant, all this is done via `HVAC_MODE` and `PRESET_MODE` (but also see `systemModeStatus`, `setpointStatus`, below). In Home Assistant schema, all this is done via a combination of `HVAC_MODE` and `PRESET_MODE` (but also see the state attributes `systemModeStatus` and `setpointStatus`, below).
## Service Calls
This integration provide service calls to expose the full functionality of evohome beyond the limitations of Home Assistant's standardised schema. Mostly, this relates to specifying the duration of mode changes, after which time the entities revert to **Auto** or **FollowSchedule** (for locations and zones, respectively).
### evohome.set_system_mode
This service call is used to set the system `mode`, either indefinitely, or for a set period of time, after which it will revert to **Auto** mode.
For some modes, such as **Away**, the duration is in `days`, where 1 day will revert after midnight, and 2 days reverts at midnight tomorrow. For other modes, such as **AutoWithEco**, the duration is in `hours`.
### evohome.reset_system
This service call is used to set the system to **AutoWithReset**, and reset all the zones to **FollowSchedule**.
### evohome.refresh_system
This service call is used to pull the latest state data from the vendor's servers.
### evohome.set_zone_override
This service call is used to set the `temperature` of a zone as identified by its `entity_id`. This change can either be indefinite, or for a set period of time, after which it will revert to **FollowSchedule**. The duration can be in `minutes` from the current time, or `until` a specified time within the next 24 hours.
### evohome.clear_zone_override
This service call is used to set a zone, as identified by its `entity_id`, to **FollowSchedule**.
## Useful Jinja Templates ## Useful Jinja Templates
The actual operating mode of evohome entities can be tracked via their state attributes, which includes a JSON data structure for the current state called `status`. The actual operating mode of evohome entities can be tracked via their state attributes, which includes a JSON data structure for the current state called `status`.
For the Controller, see `system_mode_status`: For the location (controller), see `system_mode_status`:
{% raw %} {% raw %}
```text ```text