Honeywell Total Connect Comfort (Europe)

The evohome integration links Home Assistant with all non-US Honeywell Total Connect Comfort (TCC) CH/DHW systems, such as:

• the Honeywell Evohome CH/DHW system, and
• the Honeywell Mobile Access Kit with a Round Thermostat

It does not support the home security functionality of TCC.

It uses the evohome-async client library.

For your system to be compatible with this integration, then you must be able to access it via https://international.mytotalconnectcomfort.com/ (note the ‘international’).

Configuration

To set up this integration, add the following to your configuration.yaml file:

# Example configuration.yaml entry
evohome:
  username: "YOUR_USERNAME"
  password: "YOUR_PASSWORD"

This is an IoT cloud-polling integration and the recommended minimum 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 the vendor. There is little value in shorter intervals, as this integration will automatically force a refresh shortly after any configuration changes.

Locations and Zones

TCC systems are implemented as a location, which consist of 1-12 zones and, optionally, a DHW controller:

• The system location (e.g., a house) is used for operating modes such as home, away, economy, etc.
• Heating zones (e.g., rooms) are used for the target temperature.

Evohome

Each zone is represented as a Climate entity which will expose the zone’s operating mode, current temperature and setpoint.

The Evohome location (controller) is also represented as a Climate entity that will expose the location’s operating mode. Locations have neither a current temperature nor a setpoint, but as all Climate entities are required by Home Assistant to report a temperature, this is calculated as the average of all the zones.

The DHW controller is represented as a WaterHeater entity which will report its current temperature and can be turned on or off. Due to limitations with the vendor’s RESTful API, the setpoint is not reported and cannot be changed.

Note that there is limited support for schedules: they cannot be changed and there is no facility to backup/restore that data (see here for such functionality).

Round Thermostat

These systems use an internet gateway rather than an Evohome controller. They usually have only one Round Thermostat, although they can have two. Systems with one such thermostat will still appear as two Climate entities, one for location mode (away, economy, etc.), and another for the zone setpoint.

Temperature Precision

Note that TCC devices may well measure temperatures with very high precision, but the vendor API will report temperatures rounded towards the setpoint (i.e., either up or down) with a precision of 0.5 °C; this a proxy for the deadband as used by other climate systems. Where possible, this integration will leverage an older vendor API to obtain current temperatures with a precision of 0.01 °C.

Therefore, depending upon the above, Home Assistant will display/record current temperatures with a precision of either 0.5 °C or 0.1 °C (it’s highest supported precision).

System modes, Zone overrides and Inheritance

TCC locations can support up to six distinct operating modes: Auto, AutoWithEco, Away, DayOff, HeatingOff, and Custom. Not all systems support all modes.

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 the vendor’s documentation).

For FollowSchedule, a zone’s setpoint (target temperature) is a function of its scheduled target temperature and its inherited mode:

• Auto setpoints are scheduled temperatures (the default)
• AutoWithEco setpoints are scheduled temperatures, less 3 °C

If the zone’s target temperature is changed then it will either be a TemporaryOverride or a PermanentOverride, depending. A TemporaryOverride will revert to FollowSchedule after some specified time. A PermanentOverride is a permanent change until some subsequent intervention is made. Zones can be switched between the two override modes without changing the target temperature.

For some location modes all zones will have a setpoint enforced upon them, regardless of their own mode:

• Away setpoints to 12 °C
• HeatingOff setpoints to a minimum, usually 4 °C

For Away, the DHW controller will also be turned off.

Some locations have a hidden mode, AutoWithReset, that will behave as Auto, and will reset all zones to FollowSchedule.

In the Home Assistant schema, all this is done via a combination of HVAC_MODE and PRESET_MODE (but also see the state attributes system_mode_status and setpoint_status, below).

Service Calls

This integration provides its own service calls to expose the full functionality of TCC systems beyond the limitations of Home Assistant’s standardized 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).

It is recommended to use the native service calls (e.g., evohome.set_system_mode) instead of Home Assistant’s generic equivalents (e.g., climate.set_hvac_mode) whenever possible. However, it may be necessary to use the generic service calls for integration with 3rd party systems such as Amazon Alexa or Google Home.

evohome.set_system_mode

This service call will set the operating mode of the system for a specified period of time, after which it will revert to Auto. However, if no period of time is provided, then the change is permanent.

For AutoWithEco, the period of time is a duration is up to 24 hours.

- action:
    - service: evohome.set_system_mode
      data:
        mode: AutoWithEco
        duration: {hours: 1, minutes: 30}

For the other modes, such as Away, the duration is a period of days, where 1 day will revert at midnight tonight, and 2 days reverts at midnight tomorrow.

- action:
    - service: evohome.set_system_mode
      data:
        mode: Away
        period: {days: 30}

evohome.reset_system

This service call will set the operating mode of the system to AutoWithReset, and reset all the zones to FollowSchedule.

Not all systems support this feature.

evohome.refresh_system

This service call will immediately pull the latest state data from the vendor’s servers rather than waiting for the next scan_interval.

evohome.set_zone_override

This service call will set the setpoint of a zone, as identified by its entity_id, for a specified period of time (TemporaryOverride). However, if no period of time is provided (c.f. a duration of 0, below), then the change is permanent (PermanentOverride).

- action:
    - service: evohome.set_zone_override
      target:
        entity_id: climate.loungeroom
      data:
        setpoint: 10

The duration can be up to 24 hours, after which the zone mode will revert to schedule (FollowSchedule). If the duration is 0 hours, then the change will be until the next setpoint.

- action:
    - service: evohome.set_zone_override
      target:
        entity_id: climate.loungeroom
      data:
        setpoint: 10
        duration: {minutes: 0}

evohome.clear_zone_override

This service call is used to set a zone, as identified by its entity_id, to FollowSchedule.

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.

For the location (controller), see system_mode_status:

{% if state_attr('climate.my_home', 'status').system_mode_status.mode == "Away" %}
  The system is in Away mode
{% else %}
  The system is not in Away mode
{% endif %}

For the Zones, it is setpoint_status:

{{ state_attr('climate.kitchen', 'status').setpoint_status.setpoint_mode }}

The Zones will expose the current/upcoming scheduled setpoints:

{{ state_attr('climate.kitchen', 'status').setpoints.next_sp_temp }}

All Evohome entities may have faults, and these can be turned into sensors, or:

{% if state_attr('climate.bedroom', 'status').active_faults %}
  {% if state_attr('climate.bedroom', 'status').active_faults[0].faultType == 'TempZoneActuatorLowBattery' %}
    There is a low battery
  {% endif %}
    There is a Fault!
{% else %}
  Yay, everything is OK :)
{% endif %}