evohome-async

Python client to asynchronously access the Total Connect Comfort RESTful API.

It provides support for Resideo TCC-based systems, such as Evohome, Round Thermostat, VisionPro and others:

• it supports only EU/EMEA-based systems, please use (e.g.) somecomfort for US-based systems
• it provides Evohome support for Home Assistant and other automation platforms

NOTE: the vendor API available to this library does not currently support cooling.

This client requires the aiohttp library. If you prefer a non-async client, evohome-client uses requests instead.

CLI for schedules (currently WIP)

To install a basic CLI:

pip install 'evohome-async[cli]'

evo-client --help

For example, to backup schedules (including DHW, if any):

evo-client -u username@gmail.com -p password get-schedules --loc-idx 2 > schedules.json

... and to restore:

evo-client -u username@gmail.com -p password set-schedules --loc-idx 2 -f schedules.json

To avoid exceeding the vendor's API rate limit, it will restore the access token cache, unless you use the --no-load-tokens switch.

NOTE: the client may save your access tokens to .evo-cache.tmp: this presents a small security concern.

Example code

websession = aiohttp.ClientSession()
token_manager = TokenManager(username, password, websession)
await token_manager.load_access_token()

evo = EvohomeClient(token_manager)
await evo.setup()  # usually only once: gets the config of the user's locations

loc = evo.locations[0]
await loc.get_status()  # e.g. every few minutes: gets the status of this location

comm_task = await loc.gateways[0].systems[0].set_mode(SystemMode.AUTO)
await comm_task.wait()  # until the system has the change (raises CommTaskFailedError if not)

await token_manager.save_access_token()
await websession.close()

Differences from non-async version

It is loosely based upon https://github.com/watchforstock/evohome-client, but async-aware.

The difference between the evohome-async and evohome-client libraries are significant, but it should be relatively straightforward to port your code over to this async library should you wish.

For example, entity ID attrs are .id and no longer .dhwId, zoneId, etc.

Other differences include (but are not limited to):

• namespace is refactored (simpler), and attrs are snake_case rather than camelCase
• all datetimes are now TZ-aware internally, and exposed as such
• can import schedule JSON by name as well as by zone/dhw id
• newer API exposes a TokenManager class (for authentication) and an Auth class (for authorization)
• older API exposes a SessionManager (for authentication) and an Auth class (for authorization)
• exceptions are parochial (e.g. AuthenticationFailedError) rather than generic (TypeError)
• improved logging: better error messages when things do go wrong
• additional logging: e.g. logs a warning for any active faults
• is now fully typed, including TypedDicts and py.typed
• uses best of class linting/typing via ruff/mypy
• more extensive testing via pytest
• (WIP) extended compatibility beyond pure evohome systems (e.g. VisionPro)

Development

This is how to set up a development environment.

Prerequisites

• Python 3.14 for local dev (HA stable requires 3.14); Python 3.13 is also tested in CI
• uv

Setup

git clone https://github.com/zxdavb/evohome-async
cd evohome-async

uv sync --all-extras  # creates .venv/ Python pinned via .python-version

prek install  # install pre-commit git hooks

Running tests and linting

source .venv/bin/activate

ruff check .
ruff format --check .
mypy
pytest --cov=src --cov-report=term-missing
prek run --all-files  # all pre-commit hooks

Alternatively, prefix each command with uv run to skip activation.